anvil-dev-framework 0.1.6

package/global/lib/transcript_parser.py

@@ -0,0 +1,597 @@
+#!/usr/bin/env python3
+"""
+transcript_parser.py - JSONL transcript parsing for Anvil statusline and HUD
+
+Parses Claude Code conversation transcripts to extract:
+- Tool usage (running/completed tools)
+- Todo state from TodoWrite calls
+- Error counts and patterns
+
+Usage:
+    from transcript_parser import TranscriptParser
+
+    parser = TranscriptParser()
+    activity = parser.parse("/path/to/transcript.jsonl")
+    todos = parser.get_todos("/path/to/transcript.jsonl")
+"""
+
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# =============================================================================
+# Data Structures
+# =============================================================================
+
+
+@dataclass
+class ToolEntry:
+    """Represents a single tool invocation."""
+    name: str
+    tool_use_id: str
+    status: str  # "running", "completed", "error"
+    target: Optional[str] = None  # File path or pattern if applicable
+    started_at: Optional[str] = None
+    completed_at: Optional[str] = None
+    duration_ms: Optional[int] = None
+    error: Optional[str] = None
+    input_preview: Optional[str] = None  # Truncated input for display
+
+
+@dataclass
+class TodoItem:
+    """Represents a single todo item."""
+    content: str
+    status: str  # "pending", "in_progress", "completed"
+    active_form: Optional[str] = None
+
+
+@dataclass
+class TodoState:
+    """Current state of todos from most recent TodoWrite."""
+    items: List[TodoItem] = field(default_factory=list)
+    total: int = 0
+    completed: int = 0
+    in_progress: Optional[TodoItem] = None
+    timestamp: Optional[str] = None
+
+    @property
+    def pending(self) -> int:
+        """Count of pending items."""
+        return self.total - self.completed - (1 if self.in_progress else 0)
+
+
+@dataclass
+class ToolActivityState:
+    """Aggregate tool activity state."""
+    running: List[ToolEntry] = field(default_factory=list)
+    completed: List[ToolEntry] = field(default_factory=list)
+    error_count: int = 0
+    tool_counts: Dict[str, int] = field(default_factory=dict)
+    last_updated: Optional[str] = None
+
+    def get_top_completed(self, limit: int = 4) -> List[Tuple[str, int]]:
+        """Get top N completed tools by frequency."""
+        sorted_tools = sorted(
+            self.tool_counts.items(),
+            key=lambda x: x[1],
+            reverse=True
+        )
+        return sorted_tools[:limit]
+
+
+# =============================================================================
+# Cache Implementation
+# =============================================================================
+
+
+class ParseCache:
+    """Simple TTL cache for parsed transcript data."""
+
+    def __init__(self, ttl_seconds: float = 1.0):
+        self.ttl = ttl_seconds
+        self._cache: Dict[str, Tuple[float, Any]] = {}
+
+    def get(self, key: str) -> Optional[Any]:
+        """Get cached value if not expired."""
+        if key not in self._cache:
+            return None
+
+        timestamp, value = self._cache[key]
+        if time.time() - timestamp > self.ttl:
+            del self._cache[key]
+            return None
+
+        return value
+
+    def set(self, key: str, value: Any) -> None:
+        """Cache a value with current timestamp."""
+        self._cache[key] = (time.time(), value)
+
+    def invalidate(self, key: str) -> None:
+        """Remove a key from cache."""
+        self._cache.pop(key, None)
+
+    def clear(self) -> None:
+        """Clear all cached values."""
+        self._cache.clear()
+
+
+# =============================================================================
+# Transcript Parser
+# =============================================================================
+
+
+class TranscriptParser:
+    """Parses Claude Code JSONL transcripts for tool and todo information."""
+
+    # Tools that typically have file targets
+    FILE_TOOLS = {"Read", "Write", "Edit", "MultiEdit", "Glob", "Grep", "NotebookEdit"}
+
+    # Tools to exclude from activity tracking
+    EXCLUDED_TOOLS = {"TodoWrite", "TodoRead"}
+
+    def __init__(self, cache_ttl: float = 1.0):
+        """Initialize parser with optional cache TTL.
+
+        Args:
+            cache_ttl: Cache time-to-live in seconds (default: 1.0)
+        """
+        self._tool_cache = ParseCache(ttl_seconds=cache_ttl)
+        self._todo_cache = ParseCache(ttl_seconds=cache_ttl)
+
+    def parse(
+        self,
+        transcript_path: str,
+        max_lines: int = 1000,
+        from_end: bool = True,
+    ) -> ToolActivityState:
+        """Parse transcript for tool activity.
+
+        Args:
+            transcript_path: Path to JSONL transcript file
+            max_lines: Maximum lines to parse (for performance)
+            from_end: Parse from end of file (most recent first)
+
+        Returns:
+            ToolActivityState with running/completed tools
+        """
+        if not transcript_path or not os.path.exists(transcript_path):
+            return ToolActivityState()
+
+        # Check cache
+        cache_key = f"tools:{transcript_path}:{os.path.getmtime(transcript_path)}"
+        cached = self._tool_cache.get(cache_key)
+        if cached is not None:
+            return cached
+
+        # Parse the transcript
+        result = self._parse_tools(transcript_path, max_lines, from_end)
+
+        # Cache the result
+        self._tool_cache.set(cache_key, result)
+
+        return result
+
+    def get_todos(self, transcript_path: str) -> TodoState:
+        """Extract current todo state from transcript.
+
+        Args:
+            transcript_path: Path to JSONL transcript file
+
+        Returns:
+            TodoState from most recent TodoWrite call
+        """
+        if not transcript_path or not os.path.exists(transcript_path):
+            return TodoState()
+
+        # Check cache
+        cache_key = f"todos:{transcript_path}:{os.path.getmtime(transcript_path)}"
+        cached = self._todo_cache.get(cache_key)
+        if cached is not None:
+            return cached
+
+        # Parse for todos
+        result = self._parse_todos(transcript_path)
+
+        # Cache the result
+        self._todo_cache.set(cache_key, result)
+
+        return result
+
+    def _parse_tools(
+        self,
+        transcript_path: str,
+        max_lines: int,
+        from_end: bool,
+    ) -> ToolActivityState:
+        """Internal tool parsing implementation."""
+        state = ToolActivityState()
+        state.last_updated = datetime.now(timezone.utc).isoformat()
+
+        # Track tool_use -> tool_result matching
+        pending_tools: Dict[str, ToolEntry] = {}
+        seen_tool_ids: set = set()
+
+        try:
+            lines = self._read_lines(transcript_path, max_lines, from_end)
+
+            for line in lines:
+                if not line.strip():
+                    continue
+
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+                # Handle tool_use entries
+                if entry.get("type") == "tool_use":
+                    tool_use_id = entry.get("tool_use_id", "")
+                    name = entry.get("name", "")
+
+                    if name in self.EXCLUDED_TOOLS:
+                        continue
+
+                    if tool_use_id in seen_tool_ids:
+                        continue
+                    seen_tool_ids.add(tool_use_id)
+
+                    tool_input = entry.get("input", {})
+                    target = self._extract_target(name, tool_input)
+                    input_preview = self._get_input_preview(name, tool_input)
+
+                    tool_entry = ToolEntry(
+                        name=name,
+                        tool_use_id=tool_use_id,
+                        status="running",
+                        target=target,
+                        started_at=entry.get("timestamp"),
+                        input_preview=input_preview,
+                    )
+                    pending_tools[tool_use_id] = tool_entry
+
+                # Handle tool_result entries
+                elif entry.get("type") == "tool_result":
+                    tool_use_id = entry.get("tool_use_id", "")
+
+                    if tool_use_id in pending_tools:
+                        tool_entry = pending_tools.pop(tool_use_id)
+                        tool_entry.status = "completed"
+                        tool_entry.completed_at = entry.get("timestamp")
+
+                        # Check for errors
+                        is_error = entry.get("is_error", False)
+                        if is_error:
+                            tool_entry.status = "error"
+                            tool_entry.error = str(entry.get("content", ""))[:100]
+                            state.error_count += 1
+
+                        # Calculate duration if timestamps available
+                        if tool_entry.started_at and tool_entry.completed_at:
+                            try:
+                                start = datetime.fromisoformat(
+                                    tool_entry.started_at.replace('Z', '+00:00')
+                                )
+                                end = datetime.fromisoformat(
+                                    tool_entry.completed_at.replace('Z', '+00:00')
+                                )
+                                tool_entry.duration_ms = int(
+                                    (end - start).total_seconds() * 1000
+                                )
+                            except (ValueError, TypeError):
+                                pass
+
+                        state.completed.append(tool_entry)
+
+                        # Update counts
+                        name = tool_entry.name
+                        state.tool_counts[name] = state.tool_counts.get(name, 0) + 1
+
+            # Remaining pending tools are still running
+            state.running = list(pending_tools.values())
+
+            # Limit running tools display (most recent 2)
+            state.running = state.running[:2]
+
+            # Limit completed tools (most recent 10)
+            state.completed = state.completed[:10]
+
+        except Exception:
+            # Graceful degradation - return empty state on any error
+            state = ToolActivityState()
+            state.last_updated = datetime.now(timezone.utc).isoformat()
+
+        return state
+
+    def _parse_todos(self, transcript_path: str) -> TodoState:
+        """Internal todo parsing implementation."""
+        state = TodoState()
+
+        try:
+            # Read from end to find most recent TodoWrite
+            lines = self._read_lines(transcript_path, max_lines=500, from_end=True)
+
+            # Reverse to iterate from most recent first
+            for line in reversed(lines):
+                if not line.strip():
+                    continue
+
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+                # Look for TodoWrite tool_use entries
+                if (entry.get("type") == "tool_use" and
+                    entry.get("name") == "TodoWrite"):
+
+                    tool_input = entry.get("input", {})
+                    todos = tool_input.get("todos", [])
+
+                    if not todos:
+                        continue
+
+                    state.items = []
+                    state.total = len(todos)
+                    state.completed = 0
+                    state.in_progress = None
+                    state.timestamp = entry.get("timestamp")
+
+                    for todo in todos:
+                        item = TodoItem(
+                            content=todo.get("content", ""),
+                            status=todo.get("status", "pending"),
+                            active_form=todo.get("activeForm"),
+                        )
+                        state.items.append(item)
+
+                        if item.status == "completed":
+                            state.completed += 1
+                        elif item.status == "in_progress":
+                            state.in_progress = item
+
+                    # Found the most recent TodoWrite, stop
+                    break
+
+        except Exception:
+            # Graceful degradation
+            state = TodoState()
+
+        return state
+
+    def _extract_target(self, tool_name: str, tool_input: Dict[str, Any]) -> Optional[str]:
+        """Extract file/path target from tool input.
+
+        Args:
+            tool_name: Name of the tool
+            tool_input: Tool input parameters
+
+        Returns:
+            Extracted target path or pattern, or None
+        """
+        if tool_name not in self.FILE_TOOLS:
+            return None
+
+        # Try common field names for file paths
+        for field_name in ["file_path", "path", "pattern", "notebook_path"]:
+            value = tool_input.get(field_name)
+            if value:
+                return self._shorten_path(str(value))
+
+        return None
+
+    def _shorten_path(self, path: str, max_len: int = 40) -> str:
+        """Shorten a path for display.
+
+        Args:
+            path: Full path
+            max_len: Maximum length
+
+        Returns:
+            Shortened path with ... if needed
+        """
+        if len(path) <= max_len:
+            return path
+
+        # Try to show filename with partial path
+        parts = path.split("/")
+        if len(parts) >= 2:
+            filename = parts[-1]
+            parent = parts[-2]
+            short = f".../{parent}/{filename}"
+            if len(short) <= max_len:
+                return short
+            return f".../{filename}"[:max_len]
+
+        return path[:max_len - 3] + "..."
+
+    def _get_input_preview(
+        self,
+        tool_name: str,
+        tool_input: Dict[str, Any],
+        max_len: int = 50,
+    ) -> Optional[str]:
+        """Get a preview of tool input for display.
+
+        Args:
+            tool_name: Name of the tool
+            tool_input: Tool input parameters
+            max_len: Maximum preview length
+
+        Returns:
+            Input preview string or None
+        """
+        # For file tools, show the target
+        target = self._extract_target(tool_name, tool_input)
+        if target:
+            return target
+
+        # For Bash, show command
+        if tool_name == "Bash":
+            cmd = tool_input.get("command", "")
+            if len(cmd) > max_len:
+                return cmd[:max_len - 3] + "..."
+            return cmd
+
+        # For WebFetch, show URL
+        if tool_name == "WebFetch":
+            url = tool_input.get("url", "")
+            if len(url) > max_len:
+                return url[:max_len - 3] + "..."
+            return url
+
+        return None
+
+    def _read_lines(
+        self,
+        filepath: str,
+        max_lines: int,
+        from_end: bool,
+    ) -> List[str]:
+        """Read lines from file, optionally from end.
+
+        Args:
+            filepath: Path to file
+            max_lines: Maximum lines to read
+            from_end: Read from end of file
+
+        Returns:
+            List of lines
+        """
+        try:
+            with open(filepath, 'r', encoding='utf-8', errors='replace') as f:
+                if from_end:
+                    # Read all lines and take last N
+                    # For very large files, we could use seek + readline
+                    lines = f.readlines()
+                    return lines[-max_lines:]
+                else:
+                    lines = []
+                    for i, line in enumerate(f):
+                        if i >= max_lines:
+                            break
+                        lines.append(line)
+                    return lines
+        except Exception:
+            return []
+
+
+# =============================================================================
+# Convenience Functions
+# =============================================================================
+
+
+_parser: Optional[TranscriptParser] = None
+
+
+def get_parser(cache_ttl: float = 1.0) -> TranscriptParser:
+    """Get singleton parser instance."""
+    global _parser
+    if _parser is None:
+        _parser = TranscriptParser(cache_ttl=cache_ttl)
+    return _parser
+
+
+def parse_transcript(transcript_path: str) -> ToolActivityState:
+    """Parse transcript for tool activity (convenience function)."""
+    return get_parser().parse(transcript_path)
+
+
+def get_todos_from_transcript(transcript_path: str) -> TodoState:
+    """Get todos from transcript (convenience function)."""
+    return get_parser().get_todos(transcript_path)
+
+
+# =============================================================================
+# CLI Interface
+# =============================================================================
+
+
+if __name__ == "__main__":
+    import sys
+
+    if len(sys.argv) < 2:
+        print("Usage: transcript_parser.py <command> [transcript_path]")
+        print("Commands:")
+        print("  tools <path>  - Parse tool activity")
+        print("  todos <path>  - Parse todo state")
+        print("  json <path>   - Output both as JSON")
+        sys.exit(1)
+
+    command = sys.argv[1]
+    transcript_path = sys.argv[2] if len(sys.argv) > 2 else None
+
+    parser = TranscriptParser()
+
+    if command == "tools":
+        if not transcript_path:
+            print("Error: transcript path required")
+            sys.exit(1)
+
+        activity = parser.parse(transcript_path)
+        print(f"Running tools: {len(activity.running)}")
+        for tool in activity.running:
+            print(f"  - {tool.name}: {tool.target or 'N/A'}")
+
+        print(f"\nCompleted tools: {len(activity.completed)}")
+        for name, count in activity.get_top_completed():
+            print(f"  - {name}: {count}x")
+
+        print(f"\nErrors: {activity.error_count}")
+
+    elif command == "todos":
+        if not transcript_path:
+            print("Error: transcript path required")
+            sys.exit(1)
+
+        todos = parser.get_todos(transcript_path)
+        print(f"Total: {todos.total}")
+        print(f"Completed: {todos.completed}")
+        print(f"Pending: {todos.pending}")
+
+        if todos.in_progress:
+            print(f"\nIn Progress: {todos.in_progress.content}")
+            if todos.in_progress.active_form:
+                print(f"  Active Form: {todos.in_progress.active_form}")
+
+    elif command == "json":
+        if not transcript_path:
+            print("Error: transcript path required")
+            sys.exit(1)
+
+        activity = parser.parse(transcript_path)
+        todos = parser.get_todos(transcript_path)
+
+        output = {
+            "tools": {
+                "running": [
+                    {
+                        "name": t.name,
+                        "target": t.target,
+                        "started_at": t.started_at,
+                    }
+                    for t in activity.running
+                ],
+                "completed_counts": dict(activity.get_top_completed()),
+                "error_count": activity.error_count,
+            },
+            "todos": {
+                "total": todos.total,
+                "completed": todos.completed,
+                "pending": todos.pending,
+                "in_progress": {
+                    "content": todos.in_progress.content,
+                    "active_form": todos.in_progress.active_form,
+                } if todos.in_progress else None,
+            },
+        }
+        print(json.dumps(output, indent=2))
+
+    else:
+        print(f"Unknown command: {command}")
+        sys.exit(1)