agent-trace-cli 0.1.0__py3-none-any.whl

agent_trace/__init__.py

@@ -0,0 +1,3 @@
+"""agent-trace — CLI tool for tracing AI-generated code changes."""
+
+__version__ = "0.1.0"

agent_trace/blame.py

@@ -0,0 +1,471 @@
+"""
+CLI blame command — show AI attribution for file lines.
+
+Schema 2.0: attribution is binary. A line is either AI (with a matching
+ledger segment backed by hash + content evidence) or NO_ATTRIBUTION
+(everything else). No MIXED, HUMAN, or UNKNOWN labels — we never claim
+"this was a human"; we only ever assert "this matches an AI trace".
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from typing import Any
+
+from .blame_git import _git, _git_blame_porcelain, _group_into_segments, _parse_blame_porcelain
+from .blame_meta import (
+    _extract_trace_meta,
+    _load_conversation_preview,
+    _load_local_traces,
+)
+from .git_notes import ledger_from_note_for_blame, read_note
+from .ledger import load_local_ledgers
+from .storage import resolve_project_id
+from .summary import latest_summary_by_id
+
+
+def _merge_ledgers_from_git_notes(
+    git_root: str,
+    segments: list[dict[str, Any]],
+    ledgers: dict[str, dict[str, Any]],
+) -> dict[str, dict[str, Any]]:
+    """Fill in ledgers from ``refs/notes/agent-trace`` when missing locally."""
+    merged = dict(ledgers)
+    missing = {seg.get("commit_sha") for seg in segments if seg.get("commit_sha") not in merged}
+    for sha in missing:
+        if not sha:
+            continue
+        note = read_note(sha, git_root)
+        if not note:
+            continue
+        mini = ledger_from_note_for_blame(note)
+        if mini:
+            merged[sha] = mini
+    return merged
+
+
+def _attribution_type_label(attr_type: str) -> str:
+    if attr_type == "ai":
+        return "AI"
+    return "No attribution"
+
+
+def _ledger_kind(attr_type: str) -> str:
+    if attr_type == "ai":
+        return "AI"
+    return "NO_ATTRIBUTION"
+
+
+def _ranges_overlap(
+    attr_start: int, attr_end: int,
+    seg_start: int, seg_end: int,
+) -> bool:
+    return attr_start <= seg_end and attr_end >= seg_start
+
+
+def _attribute_from_ledger(
+    blame_segments: list[dict[str, Any]],
+    ledgers: dict[str, dict[str, Any]],
+    file_path: str,
+    traces: list[dict[str, Any]] | None = None,
+    summary_by_id: dict[str, str] | None = None,
+    project_id: str | None = None,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    attributed: list[dict[str, Any]] = []
+    remaining: list[dict[str, Any]] = []
+
+    trace_by_id: dict[str, dict[str, Any]] = {}
+    if traces:
+        for t in traces:
+            tid = t.get("id")
+            if tid:
+                trace_by_id[tid] = t
+
+    for seg in blame_segments:
+        commit_sha = seg["commit_sha"]
+        ledger = ledgers.get(commit_sha)
+
+        if ledger and file_path in ledger.get("files", {}):
+            file_ledger = ledger["files"][file_path]
+            line_attrs = file_ledger.get("line_attributions", [])
+
+            orig_start = seg.get("orig_start_line", seg["start_line"])
+            orig_end = seg.get("orig_end_line", seg["end_line"])
+            offset = seg["start_line"] - orig_start
+
+            overlapping: list[tuple[int, int, dict[str, Any]]] = []
+            for la in sorted(line_attrs, key=lambda x: x.get("start_line", 0)):
+                la_start = la.get("start_line", 0)
+                la_end = la.get("end_line", 0)
+                if _ranges_overlap(la_start, la_end, orig_start, orig_end):
+                    clamped_start = max(la_start, orig_start)
+                    clamped_end = min(la_end, orig_end)
+                    overlapping.append((clamped_start, clamped_end, la))
+
+            if overlapping:
+                for clamped_orig_start, clamped_orig_end, la in overlapping:
+                    final_start = clamped_orig_start + offset
+                    final_end = clamped_orig_end + offset
+                    attr_type = la.get("type", "ai")
+                    # Schema 2.0 only allows "ai" segments; anything else is
+                    # invalid data and is skipped (treated as NO_ATTRIBUTION).
+                    if attr_type != "ai":
+                        continue
+                    kind = _ledger_kind(attr_type)
+                    trace_id = la.get("trace_id")
+                    trace_rec = trace_by_id.get(trace_id) if trace_id else None
+                    label = _attribution_type_label(attr_type)
+                    meta = (
+                        _extract_trace_meta(trace_rec, file_path, (final_start + final_end) // 2)
+                        if trace_rec
+                        else {}
+                    )
+                    conv_id = la.get("conversation_id") or meta.get("conversation_id")
+                    conv_sha = meta.get("content_sha256")
+                    conv_summary = (summary_by_id or {}).get(conv_id) if conv_id else None
+                    conv_preview = (
+                        _load_conversation_preview(project_id, conv_sha)
+                        if not conv_summary
+                        else None
+                    )
+
+                    attributed.append({
+                        "start_line": final_start,
+                        "end_line": final_end,
+                        "kind": kind,
+                        "attribution_label": label,
+                        "trace_id": trace_id,
+                        "timestamp": trace_rec.get("timestamp") if trace_rec else None,
+                        "model_id": la.get("model_id") or meta.get("model_id"),
+                        "contributor_type": attr_type,
+                        "tool": trace_rec.get("tool") if trace_rec else None,
+                        "conversation_id": conv_id,
+                        "conversation_summary": conv_summary,
+                        "conversation_preview": conv_preview,
+                        "matched_range": {
+                            "start_line": la.get("start_line"),
+                            "end_line": la.get("end_line"),
+                        },
+                        "evidence": la.get("evidence"),
+                        "commit_sha": commit_sha,
+                        "signals": ["ledger"],
+                        "source": "ledger",
+                    })
+
+                covered_orig_start = overlapping[0][0]
+                covered_orig_end = overlapping[-1][1]
+                if orig_start < covered_orig_start:
+                    gap_seg = dict(seg)
+                    gap_seg["start_line"] = seg["start_line"]
+                    gap_seg["end_line"] = covered_orig_start + offset - 1
+                    gap_seg["orig_start_line"] = orig_start
+                    gap_seg["orig_end_line"] = covered_orig_start - 1
+                    n_lines = covered_orig_start - orig_start
+                    gap_seg["content_lines"] = seg["content_lines"][:n_lines]
+                    remaining.append(gap_seg)
+                if covered_orig_end < orig_end:
+                    gap_seg = dict(seg)
+                    n_before = covered_orig_end - orig_start + 1
+                    gap_seg["start_line"] = covered_orig_end + offset + 1
+                    gap_seg["end_line"] = seg["end_line"]
+                    gap_seg["orig_start_line"] = covered_orig_end + 1
+                    gap_seg["orig_end_line"] = orig_end
+                    gap_seg["content_lines"] = seg["content_lines"][n_before:]
+                    remaining.append(gap_seg)
+                continue
+
+        remaining.append(seg)
+
+    return attributed, remaining
+
+
+def _no_attribution_entry(seg: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "start_line": seg["start_line"],
+        "end_line": seg["end_line"],
+        "kind": "NO_ATTRIBUTION",
+        "attribution_label": "No attribution",
+        "trace_id": None,
+        "timestamp": None,
+        "model_id": None,
+        "contributor_type": None,
+        "tool": None,
+        "conversation_id": None,
+        "conversation_summary": None,
+        "conversation_preview": None,
+        "matched_range": None,
+        "commit_sha": seg["commit_sha"],
+        "signals": [],
+        "source": None,
+    }
+
+
+def _attribute_deterministic(
+    blame_segments: list[dict[str, Any]],
+    file_path: str,
+    ledgers: dict[str, dict[str, Any]],
+    traces: list[dict[str, Any]],
+    summary_by_id: dict[str, str] | None = None,
+    project_id: str | None = None,
+) -> list[dict[str, Any]]:
+    ledger_results: list[dict[str, Any]] = []
+    remaining = blame_segments
+    if ledgers:
+        ledger_results, remaining = _attribute_from_ledger(
+            blame_segments, ledgers, file_path, traces=traces,
+            summary_by_id=summary_by_id, project_id=project_id,
+        )
+
+    gap_results = [_no_attribution_entry(seg) for seg in remaining]
+
+    all_results = ledger_results + gap_results
+    all_results.sort(key=lambda a: (a.get("start_line", 0), a.get("end_line", 0)))
+    return all_results
+
+
+def _merge_attributions(attributions: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    if not attributions:
+        return []
+    merged: list[dict[str, Any]] = []
+    for entry in attributions:
+        if merged:
+            prev = merged[-1]
+            if (
+                prev["end_line"] + 1 >= entry["start_line"]
+                and prev.get("kind") == entry.get("kind")
+                and prev.get("trace_id") == entry.get("trace_id")
+                and prev.get("source") == entry.get("source")
+            ):
+                prev["end_line"] = entry["end_line"]
+                continue
+        merged.append(dict(entry))
+    return merged
+
+
+_BOLD = "\033[1m"
+_DIM = "\033[2m"
+_GREEN = "\033[32m"
+_RESET = "\033[0m"
+
+
+def _format_line_range(start: int, end: int) -> str:
+    if start == end:
+        return f"L{start}"
+    return f"L{start}-{end}"
+
+
+def _format_terminal(file_path: str, attributions: list[dict[str, Any]]) -> str:
+    lines: list[str] = []
+    lines.append("")
+    lines.append(f"  {_BOLD}{file_path}{_RESET}")
+    lines.append("")
+
+    for attr in attributions:
+        start = attr.get("start_line", 0)
+        end = attr.get("end_line", 0)
+        lr = _format_line_range(start, end)
+        kind = attr.get("kind", "NO_ATTRIBUTION")
+
+        if kind == "AI":
+            tag = f"{_GREEN}[AI]{_RESET}"
+        else:
+            tag = f"{_DIM}[NO ATTRIBUTION]{_RESET}"
+
+        model_id = attr.get("model_id") or ""
+        tool = attr.get("tool")
+        tool_name = ""
+        if isinstance(tool, dict):
+            tool_name = tool.get("name", "")
+        elif isinstance(tool, str):
+            tool_name = tool
+
+        model_tool = model_id
+        if tool_name:
+            model_tool = f"{model_id} via {tool_name}" if model_id else tool_name
+
+        if kind == "NO_ATTRIBUTION":
+            lines.append(f"  {lr:<12}{tag}")
+            continue
+
+        lines.append(f"  {lr:<12}{tag} {model_tool}")
+
+        if model_id:
+            lines.append(f"              {_DIM}model: {model_id}{_RESET}")
+
+        conv_summary = attr.get("conversation_summary") or ""
+        conv_preview = attr.get("conversation_preview") or ""
+        conv_id = attr.get("conversation_id") or ""
+        if conv_summary:
+            lines.append(f"              summary: {conv_summary}")
+            if conv_id:
+                lines.append(f"              {_DIM}conversation: {conv_id[:16]}{_RESET}")
+        elif conv_preview:
+            preview_line = conv_preview.replace("\n", " ").strip()
+            if len(preview_line) > 120:
+                preview_line = preview_line[:120] + "..."
+            lines.append(f"              conversation: \"{preview_line}\"")
+        elif conv_id:
+            lines.append(f"              conversation: {conv_id[:16]}")
+
+        trace_id = attr.get("trace_id") or ""
+        commit_sha = attr.get("commit_sha") or ""
+        detail_parts = []
+        if trace_id:
+            detail_parts.append(f"trace: {trace_id}")
+        if commit_sha:
+            detail_parts.append(f"commit: {commit_sha[:12]}")
+        if detail_parts:
+            lines.append(f"              {_DIM}{' | '.join(detail_parts)}{_RESET}")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _format_json(file_path: str, attributions: list[dict[str, Any]]) -> str:
+    clean: list[dict[str, Any]] = []
+    for attr in attributions:
+        entry: dict[str, Any] = {
+            "start_line": attr.get("start_line"),
+            "end_line": attr.get("end_line"),
+            "kind": attr.get("kind"),
+        }
+        if attr.get("trace_id"):
+            entry["trace_id"] = attr["trace_id"]
+        model_id = attr.get("model_id")
+        if model_id:
+            entry["model_id"] = model_id
+        contributor_type = attr.get("contributor_type")
+        if contributor_type:
+            entry["contributor_type"] = contributor_type
+        tool = attr.get("tool")
+        if isinstance(tool, dict):
+            entry["tool"] = {"name": tool.get("name", ""), "version": tool.get("version", "")}
+        elif isinstance(tool, str):
+            entry["tool"] = {"name": tool, "version": ""}
+        if attr.get("timestamp"):
+            entry["timestamp"] = attr["timestamp"]
+        if attr.get("commit_sha"):
+            entry["commit_sha"] = attr["commit_sha"]
+        if attr.get("conversation_id"):
+            entry["conversation_id"] = attr["conversation_id"]
+        if attr.get("conversation_summary"):
+            entry["conversation_summary"] = attr["conversation_summary"]
+        if attr.get("conversation_preview"):
+            entry["conversation_preview"] = attr["conversation_preview"]
+        if attr.get("signals"):
+            entry["signals"] = attr["signals"]
+        if attr.get("source"):
+            entry["source"] = attr["source"]
+        if attr.get("attribution_label"):
+            entry["attribution_label"] = attr["attribution_label"]
+        if attr.get("evidence"):
+            entry["evidence"] = attr["evidence"]
+        clean.append(entry)
+
+    return json.dumps({"file": file_path, "attributions": clean}, indent=2)
+
+
+def _filter_no_attribution(
+    attributions: list[dict[str, Any]],
+    show_no_attribution: bool,
+) -> list[dict[str, Any]]:
+    if show_no_attribution:
+        return attributions
+    return [a for a in attributions if a.get("kind") != "NO_ATTRIBUTION"]
+
+
+def _has_no_attribution(attributions: list[dict[str, Any]]) -> bool:
+    return any(a.get("kind") == "NO_ATTRIBUTION" for a in attributions)
+
+
+def blame_file(
+    file_path: str,
+    *,
+    line: int | None = None,
+    start_line: int | None = None,
+    end_line: int | None = None,
+    show_no_attribution: bool = False,
+    require_attribution: bool = False,
+    json_output: bool = False,
+    project_dir: str | None = None,
+) -> str | None:
+    cwd = project_dir if project_dir else os.getcwd()
+    abs_path = (
+        os.path.abspath(file_path)
+        if os.path.isabs(file_path)
+        else os.path.abspath(os.path.join(cwd, file_path))
+    )
+
+    if not os.path.isfile(abs_path):
+        if json_output:
+            return None
+        print(f"agent-trace blame: file not found: {file_path}", file=sys.stderr)
+        sys.exit(1)
+
+    file_dir = os.path.dirname(abs_path) or cwd
+    git_root = _git("rev-parse", "--show-toplevel", cwd=file_dir)
+    if git_root is None:
+        if json_output:
+            return None
+        print("agent-trace blame: not a git repository", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        rel_path = os.path.relpath(abs_path, git_root)
+    except ValueError:
+        rel_path = file_path
+
+    if line is not None:
+        start_line = line
+        end_line = line
+
+    raw = _git_blame_porcelain(
+        rel_path,
+        start_line=start_line,
+        end_line=end_line,
+        cwd=git_root,
+    )
+    if raw is None:
+        if json_output:
+            return None
+        print(f"agent-trace blame: git blame failed for {file_path}", file=sys.stderr)
+        sys.exit(1)
+
+    records = _parse_blame_porcelain(raw)
+    if not records:
+        if json_output:
+            return None
+        print(f"agent-trace blame: no blame data for {file_path}", file=sys.stderr)
+        sys.exit(1)
+
+    segments = _group_into_segments(records)
+
+    traces = _load_local_traces(git_root)
+    ledgers = load_local_ledgers(git_root)
+    ledgers = _merge_ledgers_from_git_notes(git_root, segments, ledgers)
+
+    pid = resolve_project_id(git_root, create=False)
+    summary_by_id = latest_summary_by_id(pid) if pid else {}
+
+    raw_attrs = _attribute_deterministic(
+        segments, rel_path, ledgers, traces,
+        summary_by_id=summary_by_id, project_id=pid,
+    )
+    attributions = _merge_attributions(raw_attrs)
+
+    if require_attribution and _has_no_attribution(attributions):
+        print(
+            "agent-trace blame: no AI attribution for one or more lines "
+            "(ledger missing, or lines were not written by a tracked AI tool).",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    out = _filter_no_attribution(attributions, show_no_attribution)
+
+    if json_output:
+        return _format_json(rel_path, out)
+    print(_format_terminal(rel_path, out))
+    return None

agent_trace/blame_git.py

@@ -0,0 +1,133 @@
+"""Git blame --porcelain parsing and segment grouping (internal)."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Any
+
+
+def _git(*args: str, cwd: str | None = None) -> str | None:
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            capture_output=True, text=True, cwd=cwd, timeout=30,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except Exception:
+        pass
+    return None
+
+
+def _git_blame_porcelain(
+    file_path: str,
+    *,
+    start_line: int | None = None,
+    end_line: int | None = None,
+    cwd: str | None = None,
+) -> str | None:
+    args = ["blame", "--porcelain"]
+    if start_line is not None and end_line is not None:
+        args.extend(["-L", f"{start_line},{end_line}"])
+    elif start_line is not None:
+        args.extend(["-L", f"{start_line},{start_line}"])
+    args.append(file_path)
+    return _git(*args, cwd=cwd)
+
+
+def _parse_blame_porcelain(raw: str) -> list[dict[str, Any]]:
+    lines = raw.split("\n")
+    records: list[dict[str, Any]] = []
+    commit_info: dict[str, dict[str, Any]] = {}
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        if not line:
+            i += 1
+            continue
+        parts = line.split()
+        if len(parts) < 3:
+            i += 1
+            continue
+        sha = parts[0]
+        if len(sha) != 40 or not all(c in "0123456789abcdef" for c in sha):
+            i += 1
+            continue
+        orig_line = int(parts[1])
+        final_line = int(parts[2])
+        i += 1
+        if sha not in commit_info:
+            info: dict[str, Any] = {}
+            while i < len(lines):
+                hline = lines[i]
+                if hline.startswith("\t"):
+                    break
+                if hline.startswith("author "):
+                    info["author"] = hline[7:]
+                elif hline.startswith("author-time "):
+                    try:
+                        info["author_time"] = int(hline[12:])
+                    except ValueError:
+                        pass
+                elif hline.startswith("summary "):
+                    info["summary"] = hline[8:]
+                elif hline.startswith("filename "):
+                    info["filename"] = hline[9:]
+                i += 1
+            commit_info[sha] = info
+        else:
+            while i < len(lines) and not lines[i].startswith("\t"):
+                hline = lines[i]
+                if hline.startswith("filename "):
+                    commit_info[sha]["filename"] = hline[9:]
+                i += 1
+        content = ""
+        if i < len(lines) and lines[i].startswith("\t"):
+            content = lines[i][1:]
+            i += 1
+        info = commit_info.get(sha, {})
+        records.append({
+            "commit_sha": sha,
+            "orig_line": orig_line,
+            "final_line": final_line,
+            "content": content,
+            "author": info.get("author", ""),
+            "author_time": info.get("author_time"),
+            "summary": info.get("summary", ""),
+            "filename": info.get("filename", ""),
+        })
+    return records
+
+
+def _group_into_segments(records: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    if not records:
+        return []
+    segments: list[dict[str, Any]] = []
+    current: dict[str, Any] | None = None
+    for rec in records:
+        if (
+            current is not None
+            and current["commit_sha"] == rec["commit_sha"]
+            and current["end_line"] + 1 == rec["final_line"]
+        ):
+            current["end_line"] = rec["final_line"]
+            current["orig_end_line"] = rec["orig_line"]
+            current["content_lines"].append(rec["content"])
+        else:
+            if current is not None:
+                segments.append(current)
+            current = {
+                "commit_sha": rec["commit_sha"],
+                "start_line": rec["final_line"],
+                "end_line": rec["final_line"],
+                "orig_start_line": rec["orig_line"],
+                "orig_end_line": rec["orig_line"],
+                "content_lines": [rec["content"]],
+                "author": rec.get("author", ""),
+                "author_time": rec.get("author_time"),
+                "summary": rec.get("summary", ""),
+                "filename": rec.get("filename", ""),
+            }
+    if current is not None:
+        segments.append(current)
+    return segments