ai-code-stats 0.1.0__py3-none-any.whl

ai_code_stats/__init__.py

@@ -0,0 +1,15 @@
+"""ai-code-stats: 统计 CodingAgent 生成代码的采纳率、AI 代码行数与 token 消耗。
+
+按 git 仓库 × 提交人维度，在每次提交时上报本次提交的总代码行数、AI 代码行数、
+AI 占比、采纳率以及 token 用量。支持 Claude Code 与 Codex 两种 Agent，
+上报后端可插拔（HTTP webhook / 本地 JSON 文件 / 自定义命令）。
+"""
+
+__version__ = "0.1.0"
+
+# 数据契约版本：JSON Schema 与上报信封共用，破坏性变更时递增。
+SCHEMA_VERSION = "1.0"
+
+PLUGIN_NAME = "ai-code-stats"
+
+__all__ = ["__version__", "SCHEMA_VERSION", "PLUGIN_NAME"]

ai_code_stats/agents/__init__.py

@@ -0,0 +1 @@
+"""Agent 适配层：把不同 CodingAgent 的钩子载荷归一成统一的捕获结果。"""

ai_code_stats/agents/base.py

@@ -0,0 +1,40 @@
+"""Agent 适配器抽象接口。
+
+每个适配器把某个 Agent 的钩子 stdin 载荷解析成统一的 :class:`HookCapture`：
+一次 hook 触发涉及的文件编辑列表 + 该 session 的累计 token 用量 + session/cwd。
+上层 ``hooks/tool_event`` 不关心 Agent 差异，只消费 ``HookCapture``。
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class ParsedEdit:
+    """一次文件编辑解析结果。``added``/``removed`` 为去掉 diff 前缀后的纯文本行。"""
+
+    file_path: str
+    tool: str
+    added: List[str] = field(default_factory=list)
+    removed: List[str] = field(default_factory=list)
+
+
+@dataclass
+class HookCapture:
+    session_id: str
+    cwd: Optional[str]
+    edits: List[ParsedEdit] = field(default_factory=list)
+    # 该 session 到目前为止的累计 token 用量（{} 表示未知）。
+    cumulative_usage: Dict[str, int] = field(default_factory=dict)
+
+
+class AgentAdapter(ABC):
+    name: str = ""
+
+    @abstractmethod
+    def parse(self, payload: Dict[str, Any]) -> HookCapture:
+        """把钩子 stdin 载荷解析成 :class:`HookCapture`。"""
+        raise NotImplementedError

ai_code_stats/agents/claude_code.py

@@ -0,0 +1,95 @@
+"""Claude Code 适配器。
+
+PostToolUse 钩子 stdin 载荷（JSON）：
+    {
+      "session_id": "...",
+      "transcript_path": "/path/to/session.jsonl",
+      "cwd": "/abs/cwd",
+      "hook_event_name": "PostToolUse",
+      "tool_name": "Edit" | "Write" | "MultiEdit",
+      "tool_input": {...},
+      "tool_response": {...}
+    }
+
+token 用量从 transcript JSONL 累计：每条 assistant 消息带 ``message.usage``。
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List
+
+from ..diffutil import added_lines_between
+from .base import AgentAdapter, HookCapture, ParsedEdit
+
+
+class ClaudeCodeAdapter(AgentAdapter):
+    name = "claude_code"
+
+    def parse(self, payload: Dict[str, Any]) -> HookCapture:
+        session_id = str(payload.get("session_id", ""))
+        cwd = payload.get("cwd")
+        edits = self._parse_edits(payload)
+        usage = self._read_usage(payload.get("transcript_path"))
+        return HookCapture(
+            session_id=session_id, cwd=cwd, edits=edits, cumulative_usage=usage
+        )
+
+    # ------------------------------------------------------------------
+    def _parse_edits(self, payload: Dict[str, Any]) -> List[ParsedEdit]:
+        tool = str(payload.get("tool_name", ""))
+        ti = payload.get("tool_input") or {}
+        if not isinstance(ti, dict):
+            return []
+        file_path = ti.get("file_path") or ti.get("path") or ""
+
+        if tool == "Write":
+            content = ti.get("content", "") or ""
+            return [ParsedEdit(file_path=file_path, tool=tool,
+                               added=content.splitlines(), removed=[])]
+
+        if tool == "Edit":
+            added, removed = added_lines_between(
+                ti.get("old_string", "") or "", ti.get("new_string", "") or ""
+            )
+            return [ParsedEdit(file_path=file_path, tool=tool, added=added, removed=removed)]
+
+        if tool == "MultiEdit":
+            added: List[str] = []
+            removed: List[str] = []
+            for e in ti.get("edits", []) or []:
+                a, r = added_lines_between(
+                    e.get("old_string", "") or "", e.get("new_string", "") or ""
+                )
+                added.extend(a)
+                removed.extend(r)
+            return [ParsedEdit(file_path=file_path, tool=tool, added=added, removed=removed)]
+
+        # 其它工具（Bash/Read/...）不产生 AI 代码归因。
+        return []
+
+    def _read_usage(self, transcript_path: Any) -> Dict[str, int]:
+        agg = {"input": 0, "output": 0, "cache_read": 0}
+        if not transcript_path:
+            return {}
+        try:
+            with open(transcript_path, "r", encoding="utf-8") as fh:
+                for line in fh:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        obj = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    msg = obj.get("message") if isinstance(obj, dict) else None
+                    usage = msg.get("usage") if isinstance(msg, dict) else None
+                    if not isinstance(usage, dict):
+                        continue
+                    agg["input"] += int(usage.get("input_tokens", 0) or 0)
+                    agg["input"] += int(usage.get("cache_creation_input_tokens", 0) or 0)
+                    agg["output"] += int(usage.get("output_tokens", 0) or 0)
+                    agg["cache_read"] += int(usage.get("cache_read_input_tokens", 0) or 0)
+        except OSError:
+            return {}
+        return agg

ai_code_stats/agents/codex.py

@@ -0,0 +1,174 @@
+"""Codex CLI 适配器。
+
+Codex 的两条信息源：
+- **编辑**：通过 ``apply_patch`` 工具调用，补丁文本随钩子载荷传入；本适配器从
+  载荷中提取补丁字符串并解析新增/删除行。
+- **token**：每个会话持久化为 ``$CODEX_HOME/sessions/YYYY/MM/DD/rollout-<id>.jsonl``
+  （``CODEX_HOME`` 默认 ``~/.codex``），其中 ``token_count`` 事件带累计用量。
+  本适配器按 session_id 定位该文件并读取最新累计值。
+
+由于 Codex 钩子载荷 schema 仍在演进，编辑解析做成「容错扫描」：在载荷里找任何
+形似补丁的字符串来解析，找不到就只上报 token。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ..diffutil import parse_patch
+from .base import AgentAdapter, HookCapture, ParsedEdit
+
+
+class CodexAdapter(AgentAdapter):
+    name = "codex"
+
+    def parse(self, payload: Dict[str, Any]) -> HookCapture:
+        session_id = self._session_id(payload)
+        cwd = payload.get("cwd") or self._nested(payload, ["session", "cwd"])
+        edits = self._parse_edits(payload)
+        usage = self._read_usage(session_id, payload)
+        return HookCapture(
+            session_id=session_id, cwd=cwd, edits=edits, cumulative_usage=usage
+        )
+
+    # ------------------------------------------------------------------
+    def _session_id(self, payload: Dict[str, Any]) -> str:
+        for key in ("session_id", "sessionId"):
+            if payload.get(key):
+                return str(payload[key])
+        nested = self._nested(payload, ["session", "id"])
+        return str(nested) if nested else ""
+
+    @staticmethod
+    def _nested(d: Dict[str, Any], path: List[str]) -> Any:
+        node: Any = d
+        for p in path:
+            if isinstance(node, dict) and p in node:
+                node = node[p]
+            else:
+                return None
+        return node
+
+    def _candidate_patch_strings(self, payload: Dict[str, Any]) -> List[str]:
+        out: List[str] = []
+
+        def collect(v: Any) -> None:
+            if isinstance(v, str):
+                if "*** Begin Patch" in v or "@@" in v or v.lstrip().startswith(("+", "-")):
+                    out.append(v)
+            elif isinstance(v, dict):
+                for sub in v.values():
+                    collect(sub)
+            elif isinstance(v, list):
+                for sub in v:
+                    collect(sub)
+
+        for key in ("tool_input", "input", "patch", "arguments", "command", "tool_response"):
+            if key in payload:
+                collect(payload[key])
+        return out
+
+    def _parse_edits(self, payload: Dict[str, Any]) -> List[ParsedEdit]:
+        tool = str(payload.get("tool_name", "apply_patch"))
+        edits: List[ParsedEdit] = []
+        for patch in self._candidate_patch_strings(payload):
+            for pf in parse_patch(patch):
+                edits.append(
+                    ParsedEdit(file_path=pf.path, tool=tool,
+                               added=pf.added, removed=pf.removed)
+                )
+        return edits
+
+    # ------------------------------------------------------------------
+    def codex_home(self) -> Path:
+        return Path(os.environ.get("CODEX_HOME", str(Path.home() / ".codex")))
+
+    def _find_rollout(self, session_id: str, payload: Dict[str, Any]) -> Optional[Path]:
+        # 载荷可能直接给了 rollout 路径。
+        for key in ("rollout_path", "transcript_path", "session_path"):
+            p = payload.get(key)
+            if p and Path(p).is_file():
+                return Path(p)
+        if not session_id:
+            return None
+        sessions = self.codex_home() / "sessions"
+        if not sessions.is_dir():
+            return None
+        matches = list(sessions.rglob(f"*{session_id}*.jsonl"))
+        if matches:
+            # 取最新修改的一个。
+            return max(matches, key=lambda p: p.stat().st_mtime)
+        return None
+
+    def _read_usage(self, session_id: str, payload: Dict[str, Any]) -> Dict[str, int]:
+        # 载荷自带 usage 时优先用。
+        inline = self._extract_usage_obj(payload)
+        if inline:
+            return inline
+
+        path = self._find_rollout(session_id, payload)
+        if path is None:
+            return {}
+        last: Dict[str, int] = {}
+        try:
+            with open(path, "r", encoding="utf-8") as fh:
+                for line in fh:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        obj = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    found = self._extract_usage_obj(obj)
+                    if found:
+                        last = found  # token_count 累计，保留最后一个
+        except OSError:
+            return {}
+        return last
+
+    def _extract_usage_obj(self, obj: Any) -> Dict[str, int]:
+        """在任意嵌套结构里找 usage，归一为 {input,output,cache_read}。
+
+        优先 ``total_token_usage``（累计），否则用形似 usage 的对象
+        （含 ``input_tokens`` 与 ``output_tokens``）。
+        """
+        result: Dict[str, int] = {}
+
+        def walk(node: Any) -> None:
+            nonlocal result
+            if isinstance(node, dict):
+                if isinstance(node.get("total_token_usage"), dict):
+                    result = self._normalize_codex_usage(node["total_token_usage"])
+                    return
+                if "input_tokens" in node and "output_tokens" in node:
+                    result = self._normalize_codex_usage(node)
+                    # 继续找可能存在的 total_token_usage（更优）
+                for v in node.values():
+                    walk(v)
+            elif isinstance(node, list):
+                for v in node:
+                    walk(v)
+
+        walk(obj)
+        return result
+
+    @staticmethod
+    def _normalize_codex_usage(u: Dict[str, Any]) -> Dict[str, int]:
+        def g(*keys: str) -> int:
+            for k in keys:
+                if k in u and u[k] is not None:
+                    try:
+                        return int(u[k])
+                    except (TypeError, ValueError):
+                        return 0
+            return 0
+
+        return {
+            "input": g("input_tokens"),
+            "output": g("output_tokens") + g("reasoning_output_tokens"),
+            "cache_read": g("cached_input_tokens", "cache_read_input_tokens"),
+        }

ai_code_stats/agents/registry.py

@@ -0,0 +1,25 @@
+"""Agent 适配器注册表。"""
+
+from __future__ import annotations
+
+from typing import Dict, Type
+
+from .base import AgentAdapter
+from .claude_code import ClaudeCodeAdapter
+from .codex import CodexAdapter
+
+_REGISTRY: Dict[str, Type[AgentAdapter]] = {
+    ClaudeCodeAdapter.name: ClaudeCodeAdapter,
+    CodexAdapter.name: CodexAdapter,
+}
+
+
+def get_adapter(name: str) -> AgentAdapter:
+    cls = _REGISTRY.get(name)
+    if cls is None:
+        raise KeyError(f"未知 Agent 适配器: {name}（可用: {', '.join(_REGISTRY)}）")
+    return cls()
+
+
+def available_agents() -> list:
+    return list(_REGISTRY)

ai_code_stats/attribution.py

@@ -0,0 +1,141 @@
+"""归因引擎：把 commit 的新增行与窗口内 AI 生成行做指纹匹配，算采纳率与 AI 占比。
+
+定义（raw 与 effective 各算一份）：
+    采纳率 adoption_rate   = 落入本次 commit 的 AI 行数 / 窗口内 AI 生成的行数
+    AI 占比 ai_share       = 落入本次 commit 的 AI 行数 / 本次 commit 总新增行数
+
+匹配用「归一化内容哈希的多重集」实现：
+- 同一文件优先匹配；匹配不到再回退全局（覆盖文件移动/重命名导致的行位移）。
+- 消费式匹配：每个 AI 指纹最多被一条 commit 行命中一次，避免重复计数。
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from typing import Dict, Iterable, List, Tuple
+
+from .classify import Classifier
+from .models import AIEditEvent, AIModeMetrics, ModeMetrics
+
+
+def normalize_line(text: str, mode: str = "strip") -> str:
+    if mode == "strip":
+        return text.strip()
+    return text
+
+
+def line_hash(normalized: str) -> str:
+    return "sha256:" + hashlib.sha256(normalized.encode("utf-8")).hexdigest()
+
+
+def _participates(normalized: str, min_line_length: int) -> bool:
+    """归一化后长度不足的行（如孤立的 ``}``）不参与指纹匹配，降低误命中。"""
+    return len(normalized) >= max(min_line_length, 1)
+
+
+@dataclass
+class FileDiff:
+    """一个文件在本次 commit 中的变更（已按文件过滤纳入统计）。"""
+
+    path: str
+    added: List[str] = field(default_factory=list)
+    removed: List[str] = field(default_factory=list)
+    is_rename: bool = False
+
+
+class FingerprintPool:
+    """可消费的 AI 行指纹多重集：按文件分桶，支持回退全局匹配。"""
+
+    def __init__(self) -> None:
+        self.by_file: Dict[str, Counter] = defaultdict(Counter)
+
+    def add(self, file_path: str, h: str) -> None:
+        self.by_file[file_path][h] += 1
+
+    def consume(self, file_path: str, h: str) -> bool:
+        """优先在同文件桶消费一个 ``h``；没有则回退到任意文件桶。"""
+        ctr = self.by_file.get(file_path)
+        if ctr is not None and ctr.get(h, 0) > 0:
+            ctr[h] -= 1
+            return True
+        for other in self.by_file.values():
+            if other.get(h, 0) > 0:
+                other[h] -= 1
+                return True
+        return False
+
+
+@dataclass
+class AttributionResult:
+    totals_raw: ModeMetrics
+    totals_effective: ModeMetrics
+    ai_raw: AIModeMetrics
+    ai_effective: AIModeMetrics
+
+
+def _rate(numerator: int, denominator: int) -> float:
+    return (numerator / denominator) if denominator else 0.0
+
+
+def compute_attribution(
+    events: Iterable[AIEditEvent],
+    file_diffs: Iterable[FileDiff],
+    classifier: Classifier,
+    min_line_length: int = 1,
+    normalize: str = "strip",
+) -> AttributionResult:
+    """核心计算。``events`` 为窗口内 AI 编辑事件，``file_diffs`` 为本次 commit 变更。"""
+    pool = FingerprintPool()
+    gen_raw = 0
+    gen_eff = 0
+    for ev in events:
+        for al in ev.added_lines:
+            norm = normalize_line(al.text, normalize)
+            if not _participates(norm, min_line_length):
+                continue
+            gen_raw += 1
+            if al.is_effective:
+                gen_eff += 1
+            pool.add(ev.file_path, line_hash(norm))
+
+    tot_added_raw = tot_added_eff = 0
+    tot_removed_raw = tot_removed_eff = 0
+    ai_added_raw = ai_added_eff = 0
+
+    for fd in file_diffs:
+        added_flags = classifier.classify_lines(fd.added, fd.path)
+        removed_flags = classifier.classify_lines(fd.removed, fd.path)
+        tot_added_raw += len(fd.added)
+        tot_added_eff += sum(1 for f in added_flags if f)
+        tot_removed_raw += len(fd.removed)
+        tot_removed_eff += sum(1 for f in removed_flags if f)
+
+        for line, is_eff in zip(fd.added, added_flags):
+            norm = normalize_line(line, normalize)
+            if not _participates(norm, min_line_length):
+                continue
+            if pool.consume(fd.path, line_hash(norm)):
+                ai_added_raw += 1
+                if is_eff:
+                    ai_added_eff += 1
+
+    ai_raw = AIModeMetrics(
+        ai_lines_added=ai_added_raw,
+        ai_lines_generated_in_window=gen_raw,
+        adoption_rate=_rate(ai_added_raw, gen_raw),
+        ai_share_of_commit=_rate(ai_added_raw, tot_added_raw),
+    )
+    ai_eff = AIModeMetrics(
+        ai_lines_added=ai_added_eff,
+        ai_lines_generated_in_window=gen_eff,
+        adoption_rate=_rate(ai_added_eff, gen_eff),
+        ai_share_of_commit=_rate(ai_added_eff, tot_added_eff),
+    )
+    return AttributionResult(
+        totals_raw=ModeMetrics(tot_added_raw, tot_removed_raw),
+        totals_effective=ModeMetrics(tot_added_eff, tot_removed_eff),
+        ai_raw=ai_raw,
+        ai_effective=ai_eff,
+    )