@0dai-dev/cli 4.3.6 → 4.3.8

package/lib/python/heatmap.py

@@ -0,0 +1,943 @@
+#!/usr/bin/env python3
+"""Repo heatmap: LOC x agent-edit intensity.
+
+The heatmap is intentionally split into two layers:
+- repository structure + LOC provide the treemap area
+- swarm task history provides the intensity signal
+
+Modes:
+  edits       Completed task touches per file
+  failures    Failed task touches per file
+  authorship  Distinct agents touching a file
+
+The script can emit JSON for the dashboard, print a concise summary for the
+CLI, and export a 1200x630 PNG for shareable snapshots.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import pathlib
+import re
+import subprocess
+import time
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Any, Iterable
+
+try:  # Pillow is needed ONLY for `--png`; the text + `--json` paths never touch it.
+    from PIL import Image, ImageColor, ImageDraw, ImageFont
+except ModuleNotFoundError:  # npm-installed users may lack Pillow — degrade, don't crash at import.
+    Image = ImageColor = ImageDraw = ImageFont = None  # type: ignore[assignment]
+
+
+SUPPORTED_MODES = ("edits", "failures", "authorship")
+
+RENDER_SKIP_PREFIXES = {
+    ".git",
+    ".next",
+    ".tox",
+    ".venv",
+    "build",
+    "coverage",
+    "dist",
+    "node_modules",
+    "venv",
+}
+
+RENDER_SKIP_DIR_PREFIXES = (
+    "ai/swarm/",
+    "ai/outcomes/tasks/",
+    "ai/experience/events/",
+)
+
+RENDER_SKIP_SUFFIXES = {
+    ".gif",
+    ".ico",
+    ".jpg",
+    ".jpeg",
+    ".lock",
+    ".mp4",
+    ".pdf",
+    ".png",
+    ".sqlite",
+    ".sqlite3",
+    ".svg",
+    ".tar",
+    ".tgz",
+    ".webp",
+    ".woff",
+    ".woff2",
+    ".zip",
+    ".jsonl",
+}
+
+TEXT_PATH_RE = re.compile(
+    r"""
+    (?P<path>
+        (?:file://)?(?:/[^\s)\]\}<>]+)+\.[A-Za-z0-9]{1,8}
+        |
+        (?:\./|\../)?(?:[\w.-]+/)+[\w.-]+\.[A-Za-z0-9]{1,8}
+        |
+        [\w.-]+\.[A-Za-z0-9]{1,8}
+    )
+    """,
+    re.VERBOSE,
+)
+
+NO_EDIT_PHRASES = (
+    "analysis only",
+    "did not modify",
+    "no files modified",
+    "no files were modified",
+    "read only",
+    "read-only",
+    "report only",
+)
+
+MODE_INFO = {
+    "edits": {
+        "label": "completed task touches",
+        "summary": "Completed swarm tasks that touched a file",
+    },
+    "failures": {
+        "label": "failed task touches",
+        "summary": "Failed swarm tasks that touched a file",
+    },
+    "authorship": {
+        "label": "distinct agent authors",
+        "summary": "Distinct agents that touched a file",
+    },
+}
+
+PALETTE = [
+    (15, 23, 42),   # slate
+    (8, 145, 178),  # cyan
+    (245, 158, 11), # amber
+    (239, 68, 68),  # red
+]
+
+DEFAULT_WIDTH = 1200
+DEFAULT_HEIGHT = 630
+HEADER_HEIGHT = 98
+FOOTER_HEIGHT = 70
+PADDING = 14
+
+
+@dataclass
+class TreeNode:
+    name: str
+    path: str
+    kind: str = "dir"
+    loc: float = 0.0
+    weight: float = 0.0
+    intensity: float = 0.0
+    agents: set[str] = field(default_factory=set)
+    children: dict[str, "TreeNode"] = field(default_factory=dict)
+    x: float = 0.0
+    y: float = 0.0
+    width: float = 0.0
+    height: float = 0.0
+
+
+def _repo_root(target: pathlib.Path | str) -> pathlib.Path:
+    return pathlib.Path(target).expanduser().resolve()
+
+
+def _utc_now_iso() -> str:
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+
+def _run_git(target: pathlib.Path, *args: str) -> str:
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            cwd=str(target),
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=False,
+            timeout=30,
+        )
+    except Exception:  # noqa: BLE001 — git subprocess error
+        return ""
+    if result.returncode != 0:
+        return ""
+    return result.stdout
+
+
+def _git_file_list(target: pathlib.Path) -> list[str]:
+    raw = _run_git(
+        target,
+        "ls-files",
+        "-z",
+        "--cached",
+        "--others",
+        "--exclude-standard",
+    )
+    if not raw:
+        return []
+    return [entry for entry in raw.split("\0") if entry]
+
+
+def _walk_file_list(target: pathlib.Path) -> list[str]:
+    files: list[str] = []
+    for item in target.rglob("*"):
+        if not item.is_file():
+            continue
+        try:
+            rel = item.relative_to(target)
+        except ValueError:
+            continue
+        files.append(rel.as_posix())
+    return files
+
+
+def _should_render_file(rel_path: str) -> bool:
+    if not rel_path or rel_path.endswith("/"):
+        return False
+    path = pathlib.PurePosixPath(rel_path)
+    if any(part in RENDER_SKIP_PREFIXES for part in path.parts):
+        return False
+    if any(rel_path.startswith(prefix) for prefix in RENDER_SKIP_DIR_PREFIXES):
+        return False
+    if path.suffix.lower() in RENDER_SKIP_SUFFIXES:
+        return False
+    return True
+
+
+def _read_text(path: pathlib.Path) -> str | None:
+    try:
+        data = path.read_bytes()
+    except OSError:
+        return None
+    if b"\0" in data[:4096]:
+        return None
+    try:
+        return data.decode("utf-8", errors="replace")
+    except UnicodeDecodeError:
+        return None
+
+
+def _count_loc(text: str | None) -> int:
+    if not text:
+        return 0
+    return sum(1 for line in text.splitlines() if line.strip())
+
+
+def _iter_string_values(value: Any) -> Iterable[str]:
+    if isinstance(value, str):
+        yield value
+    elif isinstance(value, dict):
+        for item in value.values():
+            yield from _iter_string_values(item)
+    elif isinstance(value, list):
+        for item in value:
+            yield from _iter_string_values(item)
+
+
+def _normalize_candidate(raw: str, repo_root: pathlib.Path) -> str | None:
+    value = raw.strip().strip("()[]{}<>\"'`")
+    if not value:
+        return None
+    if value.startswith("file://"):
+        value = value[7:]
+    value = value.split("?", 1)[0].split("#", 1)[0]
+    if not value:
+        return None
+
+    candidate = pathlib.Path(value)
+    if candidate.is_absolute():
+        try:
+            candidate = candidate.resolve().relative_to(repo_root)
+        except (OSError, ValueError):
+            text = candidate.as_posix()
+            if text.startswith(repo_root.as_posix() + "/"):
+                text = text[len(repo_root.as_posix()) + 1 :]
+                candidate = pathlib.Path(text)
+            else:
+                return None
+    else:
+        candidate = pathlib.Path(value)
+
+    return candidate.as_posix()
+
+
+def _extract_file_refs(record: dict[str, Any], repo_root: pathlib.Path, renderable_files: set[str]) -> list[str]:
+    refs: list[str] = []
+    seen: set[str] = set()
+
+    def add_candidate(raw: str) -> None:
+        normalized = _normalize_candidate(raw, repo_root)
+        if not normalized:
+            return
+        if normalized not in renderable_files:
+            return
+        if normalized in seen:
+            return
+        seen.add(normalized)
+        refs.append(normalized)
+
+    # Prefer explicit file lists when present.
+    context = record.get("context") if isinstance(record.get("context"), dict) else {}
+    explicit_lists = []
+    if isinstance(context, dict):
+        for key in ("files", "file_paths", "targets"):
+            values = context.get(key)
+            if isinstance(values, list):
+                explicit_lists.extend(str(item) for item in values if item)
+    for key in ("files_modified", "files", "paths"):
+        values = record.get(key)
+        if isinstance(values, list):
+            explicit_lists.extend(str(item) for item in values if item)
+
+    for item in explicit_lists:
+        add_candidate(item)
+
+    # Fall back to scanning the text-bearing fields for file-like references.
+    for text in _iter_string_values(record):
+        for match in TEXT_PATH_RE.finditer(text):
+            add_candidate(match.group("path"))
+
+    return refs
+
+
+def _normal_status(record: dict[str, Any]) -> str:
+    raw = str(record.get("status") or "").strip().lower()
+    if raw:
+        return raw
+    result = str(record.get("result") or "").strip().lower()
+    if any(phrase in result for phrase in ("failed", "error", "timeout")):
+        return "failed"
+    if any(phrase in result for phrase in ("done", "complete", "committed", "implemented")):
+        return "done"
+    return ""
+
+
+def _is_read_only(record: dict[str, Any]) -> bool:
+    text = " ".join(str(item).lower() for item in _iter_string_values(record))
+    return any(phrase in text for phrase in NO_EDIT_PHRASES)
+
+
+def _agent_name(record: dict[str, Any]) -> str:
+    raw = str(record.get("completed_by") or record.get("assigned_to") or record.get("agent") or "").strip()
+    return raw.lower() or "unknown"
+
+
+def _load_task_records(target: pathlib.Path) -> list[dict[str, Any]]:
+    records: list[dict[str, Any]] = []
+    swarm_dir = target / "ai" / "swarm"
+    for section in ("done", "archive"):
+        dir_path = swarm_dir / section
+        if not dir_path.is_dir():
+            continue
+        for file_path in sorted(dir_path.glob("*.json")):
+            try:
+                records.append(json.loads(file_path.read_text(encoding="utf-8")))
+            except (OSError, json.JSONDecodeError):
+                continue
+    return records
+
+
+def _load_renderable_files(target: pathlib.Path) -> list[str]:
+    files = _git_file_list(target)
+    if not files:
+        files = _walk_file_list(target)
+    return sorted({f for f in files if _should_render_file(f)})
+
+
+def _count_records(records: list[dict[str, Any]], mode: str, repo_root: pathlib.Path, renderable_files: set[str]) -> dict[str, dict[str, Any]]:
+    counts: dict[str, dict[str, Any]] = defaultdict(
+        lambda: {
+            "intensity": 0.0,
+            "agents": set(),
+            "records": 0,
+            "failed": 0,
+            "edits": 0,
+        }
+    )
+
+    for record in records:
+        refs = _extract_file_refs(record, repo_root, renderable_files)
+        if not refs:
+            continue
+
+        status = _normal_status(record)
+        agent = _agent_name(record)
+        read_only = _is_read_only(record)
+
+        should_count = False
+        if mode == "edits":
+            should_count = status in {"done", "completed", "success", "partial", "superseded"}
+            should_count = should_count and not read_only
+        elif mode == "failures":
+            should_count = status == "failed"
+        elif mode == "authorship":
+            should_count = True
+
+        if not should_count:
+            continue
+
+        for ref in refs:
+            bucket = counts[ref]
+            bucket["records"] += 1
+            bucket["agents"].add(agent)
+            if mode == "edits":
+                bucket["edits"] += 1
+                bucket["intensity"] += 1.0
+            elif mode == "failures":
+                bucket["failed"] += 1
+                bucket["intensity"] += 1.0
+            elif mode == "authorship":
+                bucket["intensity"] = float(len(bucket["agents"]))
+
+    return counts
+
+
+def _build_tree(file_rows: list[dict[str, Any]]) -> TreeNode:
+    root = TreeNode(name="root", path="", kind="dir")
+    for row in file_rows:
+        parts = pathlib.PurePosixPath(str(row["path"])).parts
+        if not parts:
+            continue
+        node = root
+        accumulated: list[str] = []
+        for part in parts[:-1]:
+            accumulated.append(part)
+            child = node.children.get(part)
+            if child is None:
+                child = TreeNode(
+                    name=part,
+                    path="/".join(accumulated),
+                    kind="dir",
+                )
+                node.children[part] = child
+            node = child
+        leaf_name = parts[-1]
+        accumulated.append(leaf_name)
+        leaf = node.children.get(leaf_name)
+        if leaf is None:
+            leaf = TreeNode(
+                name=leaf_name,
+                path="/".join(accumulated),
+                kind="file",
+            )
+            node.children[leaf_name] = leaf
+        leaf.kind = "file"
+        leaf.loc += float(row["loc"])
+        leaf.weight += float(row["weight"])
+        leaf.intensity += float(row["intensity"])
+        leaf.agents.update(str(agent) for agent in row.get("agents", []) if agent)
+
+    def aggregate(node: TreeNode) -> None:
+        if node.kind == "file" and not node.children:
+            node.weight = max(node.weight, 1.0 if node.intensity > 0 else 0.0)
+            node.loc = float(node.loc)
+            return
+
+        loc = 0.0
+        weight = 0.0
+        intensity = 0.0
+        agents: set[str] = set()
+        for child in node.children.values():
+            aggregate(child)
+            loc += child.loc
+            weight += child.weight
+            intensity += child.intensity
+            agents.update(child.agents)
+        node.loc = loc
+        node.weight = weight
+        node.intensity = intensity
+        node.agents = agents
+
+    aggregate(root)
+    return root
+
+
+def _worst_ratio(row: list[float], side: float) -> float:
+    if not row or side <= 0:
+        return math.inf
+    total = sum(row)
+    max_item = max(row)
+    min_item = min(row)
+    total_sq = total * total
+    side_sq = side * side
+    return max((side_sq * max_item) / total_sq, total_sq / (side_sq * min_item))
+
+
+def _layout_row(row: list[float], x: float, y: float, width: float, height: float) -> tuple[list[tuple[float, float, float, float]], tuple[float, float, float, float]]:
+    rects: list[tuple[float, float, float, float]] = []
+    if not row or width <= 0 or height <= 0:
+        return rects, (x, y, width, height)
+
+    total = sum(row)
+    if width >= height:
+        row_height = total / width if width else 0
+        cursor_x = x
+        for value in row:
+            rect_width = value / row_height if row_height else 0
+            rects.append((cursor_x, y, rect_width, row_height))
+            cursor_x += rect_width
+        return rects, (x, y + row_height, width, max(0.0, height - row_height))
+
+    row_width = total / height if height else 0
+    cursor_y = y
+    for value in row:
+        rect_height = value / row_width if row_width else 0
+        rects.append((x, cursor_y, row_width, rect_height))
+        cursor_y += rect_height
+    return rects, (x + row_width, y, max(0.0, width - row_width), height)
+
+
+def _squarify(sizes: list[float], x: float, y: float, width: float, height: float) -> list[tuple[float, float, float, float]]:
+    if not sizes or width <= 0 or height <= 0:
+        return []
+    total = sum(sizes)
+    if total <= 0:
+        return []
+    scale = width * height / total
+    normalized = sorted((size * scale for size in sizes), reverse=True)
+
+    rects: list[tuple[float, float, float, float]] = []
+    row: list[float] = []
+    side = min(width, height)
+    remaining = normalized[:]
+    current = (x, y, width, height)
+
+    while remaining:
+        item = remaining[0]
+        test_row = row + [item]
+        if not row or _worst_ratio(test_row, side) <= _worst_ratio(row, side):
+            row = test_row
+            remaining.pop(0)
+            if not remaining:
+                row_rects, current = _layout_row(row, *current)
+                rects.extend(row_rects)
+                row = []
+        else:
+            row_rects, current = _layout_row(row, *current)
+            rects.extend(row_rects)
+            row = []
+            side = min(current[2], current[3])
+
+    if row:
+        row_rects, current = _layout_row(row, *current)
+        rects.extend(row_rects)
+
+    return rects
+
+
+def _layout_tree(node: TreeNode, x: float, y: float, width: float, height: float, depth: int = 0) -> None:
+    node.x = x
+    node.y = y
+    node.width = width
+    node.height = height
+
+    if not node.children:
+        return
+
+    child_nodes = sorted(node.children.values(), key=lambda item: (item.weight, item.loc, item.path), reverse=True)
+    child_weights = [max(child.weight, 0.5 if child.intensity > 0 else 0.0) for child in child_nodes]
+    if sum(child_weights) <= 0:
+        return
+
+    inner_pad = 1.5 if depth < 3 else 1.0
+    inner_x = x + inner_pad
+    inner_y = y + inner_pad
+    inner_w = max(0.0, width - inner_pad * 2)
+    inner_h = max(0.0, height - inner_pad * 2)
+    rects = _squarify(child_weights, inner_x, inner_y, inner_w, inner_h)
+    for child, (cx, cy, cw, ch) in zip(child_nodes, rects):
+        _layout_tree(child, cx, cy, cw, ch, depth + 1)
+
+
+def _collect_leaves(node: TreeNode) -> list[TreeNode]:
+    leaves: list[TreeNode] = []
+    if not node.children:
+        if node.kind == "file":
+            leaves.append(node)
+        return leaves
+    for child in node.children.values():
+        leaves.extend(_collect_leaves(child))
+    return leaves
+
+
+def _hex_to_rgb(value: str) -> tuple[int, int, int]:
+    return ImageColor.getrgb(value)
+
+
+def _lerp(a: float, b: float, t: float) -> float:
+    return a + (b - a) * t
+
+
+def _color_for_value(value: float, max_value: float) -> str:
+    if max_value <= 0:
+        return "#334155"
+    if value <= 0:
+        return "#233044"
+    t = math.log1p(value) / math.log1p(max_value) if max_value > 1 else 1.0
+    t = max(0.0, min(1.0, t))
+    if t <= 0.33:
+        inner = t / 0.33
+        left, right = PALETTE[0], PALETTE[1]
+    elif t <= 0.66:
+        inner = (t - 0.33) / 0.33
+        left, right = PALETTE[1], PALETTE[2]
+    else:
+        inner = (t - 0.66) / 0.34
+        left, right = PALETTE[2], PALETTE[3]
+    rgb = tuple(int(round(_lerp(left[i], right[i], inner))) for i in range(3))
+    return "#%02x%02x%02x" % rgb
+
+
+def _luminance(hex_value: str) -> float:
+    r, g, b = _hex_to_rgb(hex_value)
+    return (0.2126 * r + 0.7152 * g + 0.0722 * b) / 255.0
+
+
+def _fit_text(draw: ImageDraw.ImageDraw, text: str, font: ImageFont.ImageFont, max_width: float) -> str:
+    if draw.textbbox((0, 0), text, font=font)[2] <= max_width:
+        return text
+    ellipsis = "…"
+    clipped = text
+    while clipped and draw.textbbox((0, 0), clipped + ellipsis, font=font)[2] > max_width:
+        clipped = clipped[:-1]
+    return clipped + ellipsis if clipped else ellipsis
+
+
+def _load_font(size: int, bold: bool = False, mono: bool = False) -> ImageFont.ImageFont:
+    candidates = []
+    if mono:
+        candidates.extend(
+            [
+                "/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf",
+                "/usr/share/fonts/truetype/liberation2/LiberationMono-Regular.ttf",
+            ]
+        )
+    elif bold:
+        candidates.extend(
+            [
+                "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+                "/usr/share/fonts/truetype/liberation2/LiberationSans-Bold.ttf",
+            ]
+        )
+    else:
+        candidates.extend(
+            [
+                "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+                "/usr/share/fonts/truetype/liberation2/LiberationSans-Regular.ttf",
+            ]
+        )
+    for candidate in candidates:
+        font_path = pathlib.Path(candidate)
+        if font_path.exists():
+            try:
+                return ImageFont.truetype(str(font_path), size=size)
+            except OSError:
+                continue
+    return ImageFont.load_default()
+
+
+def _flatten_leaf_records(root: TreeNode, mode: str) -> list[dict[str, Any]]:
+    leaves = _collect_leaves(root)
+    max_intensity = max((leaf.intensity for leaf in leaves), default=0.0)
+    max_weight = max((leaf.weight for leaf in leaves), default=0.0)
+
+    records: list[dict[str, Any]] = []
+    for leaf in leaves:
+        fill = _color_for_value(leaf.intensity, max_intensity)
+        rel_path = leaf.path
+        directory = str(pathlib.PurePosixPath(rel_path).parent)
+        label = pathlib.PurePosixPath(rel_path).name
+        if directory and directory != ".":
+            short_group = pathlib.PurePosixPath(directory).parts[0]
+        else:
+            short_group = "."
+        records.append(
+            {
+                "path": rel_path,
+                "directory": directory if directory != "." else "",
+                "group": short_group,
+                "label": label,
+                "loc": int(round(leaf.loc)),
+                "weight": float(leaf.weight),
+                "intensity": float(round(leaf.intensity, 3)),
+                "color": fill,
+                "x": round(leaf.x, 2),
+                "y": round(leaf.y, 2),
+                "width": round(leaf.width, 2),
+                "height": round(leaf.height, 2),
+                "agents": sorted(leaf.agents),
+                "max_weight": float(max_weight),
+            }
+        )
+    return records
+
+
+def _rank_hotspots(records: list[dict[str, Any]], limit: int = 12) -> list[dict[str, Any]]:
+    def score(item: dict[str, Any]) -> float:
+        loc = float(item.get("loc") or 0)
+        intensity = float(item.get("intensity") or 0)
+        return intensity * math.log1p(loc)
+
+    return sorted(records, key=score, reverse=True)[:limit]
+
+
+def build_heatmap_payload(target: pathlib.Path | str, mode: str = "edits", width: int = DEFAULT_WIDTH, height: int = DEFAULT_HEIGHT) -> dict[str, Any]:
+    if mode not in SUPPORTED_MODES:
+        raise ValueError(f"unsupported mode: {mode}")
+
+    repo_root = _repo_root(target)
+    renderable_files = _load_renderable_files(repo_root)
+    renderable_set = set(renderable_files)
+    task_records = _load_task_records(repo_root)
+    counts = _count_records(task_records, mode, repo_root, renderable_set)
+
+    rows: list[dict[str, Any]] = []
+    for rel_path in renderable_files:
+        file_path = repo_root / rel_path
+        text = _read_text(file_path)
+        loc = _count_loc(text)
+        intensity_data = counts.get(rel_path)
+        intensity = float(intensity_data["intensity"]) if intensity_data else 0.0
+        if loc <= 0 and intensity <= 0:
+            continue
+        weight = float(loc if loc > 0 else 1)
+        if intensity <= 0 and weight <= 0:
+            continue
+        rows.append(
+            {
+                "path": rel_path,
+                "loc": loc,
+                "weight": weight,
+                "intensity": intensity,
+                "agents": sorted(intensity_data["agents"]) if intensity_data else [],
+            }
+        )
+
+    tree = _build_tree(rows)
+    _layout_tree(tree, 0.0, 0.0, float(width), float(height), 0)
+    leaf_records = _flatten_leaf_records(tree, mode)
+    hot_spots = _rank_hotspots(leaf_records)
+
+    total_loc = sum(item["loc"] for item in leaf_records)
+    total_intensity = sum(float(item["intensity"]) for item in leaf_records)
+    touched_files = sum(1 for item in leaf_records if float(item["intensity"]) > 0)
+    max_intensity = max((float(item["intensity"]) for item in leaf_records), default=0.0)
+    max_loc = max((int(item["loc"]) for item in leaf_records), default=0)
+
+    return {
+        "mode": mode,
+        "mode_label": MODE_INFO[mode]["label"],
+        "mode_summary": MODE_INFO[mode]["summary"],
+        "generated_at": _utc_now_iso(),
+        "root": repo_root.as_posix(),
+        "width": width,
+        "height": height,
+        "legend": {
+            "area": "LOC",
+            "color": MODE_INFO[mode]["label"],
+        },
+        "stats": {
+            "files": len(leaf_records),
+            "total_loc": int(total_loc),
+            "total_intensity": round(total_intensity, 3),
+            "touched_files": touched_files,
+            "max_loc": int(max_loc),
+            "max_intensity": round(max_intensity, 3),
+        },
+        "nodes": leaf_records,
+        "top_hotspots": hot_spots,
+    }
+
+
+def _draw_wrapped_text(draw: ImageDraw.ImageDraw, text: str, box: tuple[float, float, float, float], font: ImageFont.ImageFont, fill: str, max_lines: int = 2) -> None:
+    x, y, width, height = box
+    if width <= 0 or height <= 0:
+        return
+    max_width = width
+    words = text.split()
+    if not words:
+        return
+    lines: list[str] = []
+    current = words[0]
+    for word in words[1:]:
+        candidate = f"{current} {word}"
+        if draw.textbbox((0, 0), candidate, font=font)[2] <= max_width:
+            current = candidate
+        else:
+            lines.append(current)
+            current = word
+            if len(lines) >= max_lines:
+                break
+    if len(lines) < max_lines:
+        lines.append(current)
+    while len(lines) > max_lines:
+        lines.pop()
+    # Shrink the final line if needed.
+    if lines and draw.textbbox((0, 0), "\n".join(lines), font=font)[3] > height:
+        last = lines[-1]
+        lines[-1] = _fit_text(draw, last, font, max_width)
+    draw.multiline_text((x, y), "\n".join(lines), font=font, fill=fill, spacing=2)
+
+
+def render_png(payload: dict[str, Any], output_path: pathlib.Path | str) -> pathlib.Path:
+    if Image is None:  # Pillow absent (e.g. a fresh `npm install -g` without `pip install pillow`).
+        raise SystemExit(
+            "0dai heatmap --png needs Pillow, which is not installed.\n"
+            "Install it (pip install pillow) for PNG export; the default text and --json "
+            "summaries work without it."
+        )
+    width = int(payload.get("width") or DEFAULT_WIDTH)
+    height = int(payload.get("height") or DEFAULT_HEIGHT)
+    out = pathlib.Path(output_path).expanduser().resolve()
+    out.parent.mkdir(parents=True, exist_ok=True)
+
+    image = Image.new("RGBA", (width, height), "#0b0f14")
+    draw = ImageDraw.Draw(image, "RGBA")
+
+    # Background accents.
+    draw.rounded_rectangle((18, 18, width - 18, HEADER_HEIGHT - 8), radius=26, fill=(13, 17, 24, 230), outline=(255, 255, 255, 18), width=1)
+    draw.rounded_rectangle((18, HEADER_HEIGHT + 4, width - 18, height - FOOTER_HEIGHT - 14), radius=24, fill=(9, 13, 20, 255), outline=(255, 255, 255, 14), width=1)
+    draw.rounded_rectangle((18, height - FOOTER_HEIGHT + 2, width - 18, height - 12), radius=20, fill=(10, 14, 22, 240), outline=(255, 255, 255, 14), width=1)
+
+    title_font = _load_font(28, bold=True)
+    subtitle_font = _load_font(15)
+    stat_font = _load_font(17, bold=True)
+    body_font = _load_font(13)
+    mono_font = _load_font(12, mono=True)
+
+    mode = str(payload.get("mode") or "edits")
+    mode_label = str(payload.get("mode_label") or mode)
+    legend = payload.get("legend") or {}
+    stats = payload.get("stats") or {}
+
+    draw.text((42, 34), "Heatmap", font=title_font, fill="#f8fafc")
+    draw.text((42, 66), f"Area = {legend.get('area', 'LOC')}  •  Color = {mode_label}", font=subtitle_font, fill="#9ca3af")
+
+    stats_text = [
+        f"{stats.get('files', 0)} files",
+        f"{stats.get('total_loc', 0)} LOC",
+        f"{stats.get('touched_files', 0)} touched",
+    ]
+    cursor_x = width - 42
+    for item in reversed(stats_text):
+        bbox = draw.textbbox((0, 0), item, font=stat_font)
+        box_w = bbox[2] - bbox[0] + 24
+        cursor_x -= box_w
+        draw.rounded_rectangle((cursor_x, 36, cursor_x + box_w, 72), radius=16, fill=(17, 24, 39, 240), outline=(255, 255, 255, 18), width=1)
+        draw.text((cursor_x + 12, 45), item, font=stat_font, fill="#e2e8f0")
+        cursor_x -= 10
+
+    treemap_top = HEADER_HEIGHT + 18
+    treemap_bottom = height - FOOTER_HEIGHT - 22
+    treemap_left = 34
+    treemap_right = width - 34
+    treemap_w = treemap_right - treemap_left
+    treemap_h = treemap_bottom - treemap_top
+
+    nodes = payload.get("nodes") or []
+    if not nodes:
+        draw.text((treemap_left + 20, treemap_top + 20), "No renderable files found", font=stat_font, fill="#cbd5e1")
+    else:
+        max_intensity = max((float(node.get("intensity") or 0) for node in nodes), default=0.0)
+        for node in nodes:
+            x = treemap_left + float(node["x"])
+            y = treemap_top + float(node["y"])
+            w = float(node["width"])
+            h = float(node["height"])
+            if w <= 0 or h <= 0:
+                continue
+            color = str(node["color"])
+            fill = _hex_to_rgb(color)
+            rect = (x, y, x + w, y + h)
+            radius = 12 if min(w, h) > 26 else 7
+            draw.rounded_rectangle(rect, radius=radius, fill=(*fill, 230), outline=(255, 255, 255, 18), width=1)
+
+            if w < 64 or h < 36:
+                continue
+
+            label = str(node.get("label") or node.get("path") or "")
+            loc = int(node.get("loc") or 0)
+            intensity = float(node.get("intensity") or 0)
+            agents = node.get("agents") or []
+            display = _fit_text(draw, label, body_font, max(24, w - 14))
+            text_color = "#020617" if _luminance(color) > 0.56 else "#f8fafc"
+
+            _draw_wrapped_text(
+                draw,
+                display,
+                (x + 8, y + 7, max(0, w - 14), max(0, h - 22)),
+                body_font,
+                text_color,
+                max_lines=2,
+            )
+            if w > 115 and h > 54:
+                footer = f"LOC {loc}  •  intensity {intensity:g}"
+                if agents:
+                    footer += f"  •  {len(agents)} agent(s)"
+                draw.text((x + 8, y + h - 18), _fit_text(draw, footer, mono_font, max(0, w - 16)), font=mono_font, fill=text_color)
+
+    hotspots = payload.get("top_hotspots") or []
+    footer_title = f"Top hotspots • {mode_label}"
+    draw.text((42, height - FOOTER_HEIGHT + 16), footer_title, font=subtitle_font, fill="#cbd5e1")
+    hot_text = []
+    for item in hotspots[:4]:
+        hot_text.append(f"{item['label']} ({item['loc']} LOC, {float(item['intensity']):g})")
+    draw.text((42, height - FOOTER_HEIGHT + 36), _fit_text(draw, "  •  ".join(hot_text) or "No hotspots yet", mono_font, width - 84), font=mono_font, fill="#9ca3af")
+
+    image.save(out, format="PNG")
+    return out
+
+
+def _print_summary(payload: dict[str, Any]) -> None:
+    stats = payload.get("stats") or {}
+    print(f"Heatmap ({payload.get('mode')})")
+    print(
+        f"  files: {stats.get('files', 0)}  "
+        f"LOC: {stats.get('total_loc', 0)}  "
+        f"touched: {stats.get('touched_files', 0)}"
+    )
+    print(
+        f"  max LOC: {stats.get('max_loc', 0)}  "
+        f"max intensity: {stats.get('max_intensity', 0)}"
+    )
+    print()
+    print("Top hotspots:")
+    for idx, item in enumerate((payload.get("top_hotspots") or [])[:8], start=1):
+        print(
+            f"  {idx}. {item['path']}  "
+            f"(LOC {item['loc']}, intensity {float(item['intensity']):g})"
+        )
+    print()
+    print("Export PNG:")
+    print("  0dai heatmap --mode edits --png heatmap.png")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Repo heatmap: LOC x agent-edit intensity")
+    parser.add_argument("--target", default=".", help="Repository root to analyze")
+    parser.add_argument("--mode", default="edits", choices=SUPPORTED_MODES, help="Intensity mode")
+    parser.add_argument("--width", type=int, default=DEFAULT_WIDTH)
+    parser.add_argument("--height", type=int, default=DEFAULT_HEIGHT)
+    parser.add_argument("--json", action="store_true", help="Print JSON to stdout")
+    parser.add_argument("--png", default="", help="Write a PNG export to this path")
+    args = parser.parse_args(argv)
+
+    payload = build_heatmap_payload(args.target, mode=args.mode, width=args.width, height=args.height)
+
+    if args.png:
+        render_png(payload, args.png)
+
+    if args.json:
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+        return 0
+
+    _print_summary(payload)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())