gwc-pybundle 2.1.2__py3-none-any.whl

pybundle/steps/git_analytics.py

@@ -0,0 +1,315 @@
+"""Advanced git analytics step - v1.5.1
+
+Provides deep git history insights:
+- Blame-based contributor analysis
+- Branch health metrics
+- Commit message quality assessment
+- Code ownership tracking
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+from .base import StepResult
+from ..context import BundleContext
+
+
+@dataclass
+class GitAnalyticsStep:
+    """Step that performs advanced git analytics."""
+
+    name: str = "git-analytics"
+    outfile: str = "meta/100_git_analytics.txt"
+    blame_depth: int = 100  # Number of commits to analyze in blame
+
+    def run(self, ctx: BundleContext) -> StepResult:
+        """Perform comprehensive git analytics."""
+        start = time.time()
+
+        # Check if we're in a git repo
+        git_check = subprocess.run(
+            ["git", "rev-parse", "--git-dir"],
+            cwd=ctx.root,
+            capture_output=True,
+            text=True,
+        )
+
+        if git_check.returncode != 0:
+            elapsed = int((time.time() - start) * 1000)
+            return StepResult(self.name, "SKIP", elapsed, "not a git repository")
+
+        # Gather analytics
+        blame_stats = self._analyze_blame(ctx.root)
+        branch_stats = self._analyze_branches(ctx.root)
+        commit_quality = self._analyze_commit_messages(ctx.root)
+        codeowners_coverage = self._analyze_codeowners(ctx.root)
+
+        # Write report
+        out_path = ctx.workdir / self.outfile
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(out_path, "w") as f:
+            f.write("=" * 80 + "\n")
+            f.write("GIT ANALYTICS REPORT\n")
+            f.write("=" * 80 + "\n\n")
+
+            # Blame-based analysis
+            if blame_stats:
+                f.write("CONTRIBUTOR ANALYSIS (by line count)\n")
+                f.write("-" * 80 + "\n")
+                f.write(f"Analyzed last {self.blame_depth} commits\n\n")
+                for i, (author, lines, files) in enumerate(blame_stats[:10], 1):
+                    f.write(f"{i:2d}. {author:<40} {lines:>6} lines {files:>3} files\n")
+                f.write("\n")
+
+            # Branch health
+            if branch_stats:
+                f.write("BRANCH HEALTH METRICS\n")
+                f.write("-" * 80 + "\n")
+                current, ahead, behind, uncommitted = branch_stats
+                f.write(f"Current branch:      {current}\n")
+                f.write(f"Commits ahead main:  {ahead}\n")
+                f.write(f"Commits behind main: {behind}\n")
+                f.write(f"Uncommitted changes: {uncommitted} files\n\n")
+
+            # Commit message quality
+            if commit_quality:
+                f.write("COMMIT MESSAGE QUALITY\n")
+                f.write("-" * 80 + "\n")
+                conventional_pct, avg_length, total = commit_quality
+                f.write(f"Total commits analyzed: {total}\n")
+                f.write(f"Conventional commits:   {conventional_pct:.1f}%\n")
+                f.write(f"Average message length: {avg_length:.0f} chars\n")
+                f.write("(Conventional format: type(scope): description)\n\n")
+
+            # CODEOWNERS coverage
+            if codeowners_coverage:
+                f.write("CODE OWNERSHIP TRACKING\n")
+                f.write("-" * 80 + "\n")
+                if codeowners_coverage[0]:
+                    codeowners_exists, coverage_pct, rules_count = codeowners_coverage
+                    f.write(f"CODEOWNERS file:  {'Found' if codeowners_exists else 'Not found'}\n")
+                    f.write(f"Ownership rules:  {rules_count}\n")
+                    f.write(f"Files covered:    {coverage_pct:.1f}%\n\n")
+                else:
+                    f.write("CODEOWNERS file not found\n\n")
+
+            f.write("=" * 80 + "\n")
+            f.write("Git analytics complete\n")
+            f.write("=" * 80 + "\n")
+
+        elapsed = int((time.time() - start) * 1000)
+        return StepResult(self.name, "OK", elapsed, "git analytics complete")
+
+    def _analyze_blame(self, root: Path) -> List[Tuple[str, int, int]]:
+        """Analyze git blame to find top contributors by line count.
+
+        Returns list of (author, line_count, file_count) tuples sorted by lines.
+        """
+        try:
+            # Get commits in range
+            result = subprocess.run(
+                ["git", "log", f"--max-count={self.blame_depth}", "--format=%an"],
+                cwd=root,
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+
+            if result.returncode != 0:
+                return []
+
+            authors: Dict[str, Dict[str, int]] = {}
+            for commit_author in result.stdout.strip().split("\n"):
+                if commit_author:
+                    if commit_author not in authors:
+                        authors[commit_author] = {"lines": 0, "files": set()}
+
+            # For each author, run blame on all Python files
+            for py_file in root.rglob("*.py"):
+                # Skip artifacts and venv
+                if any(
+                    x in py_file.parts
+                    for x in ["artifacts", ".git", "venv", ".venv", "__pycache__"]
+                ):
+                    continue
+
+                try:
+                    blame_result = subprocess.run(
+                        ["git", "blame", "--line-porcelain", str(py_file.relative_to(root))],
+                        cwd=root,
+                        capture_output=True,
+                        text=True,
+                        timeout=10,
+                    )
+
+                    if blame_result.returncode == 0:
+                        for line in blame_result.stdout.split("\n"):
+                            if line.startswith("author "):
+                                author = line[7:].strip()
+                                if author in authors:
+                                    authors[author]["lines"] += 1
+                                    authors[author]["files"].add(str(py_file.relative_to(root)))
+
+                except Exception:
+                    continue
+
+            # Convert to list and sort
+            result_list = [
+                (author, stats["lines"], len(stats["files"]))
+                for author, stats in authors.items()
+            ]
+            return sorted(result_list, key=lambda x: x[1], reverse=True)
+
+        except Exception:
+            return []
+
+    def _analyze_branches(self, root: Path) -> Tuple[str, int, int, int] | None:
+        """Analyze branch health metrics.
+
+        Returns (current_branch, commits_ahead, commits_behind, uncommitted_files).
+        """
+        try:
+            # Get current branch
+            branch_result = subprocess.run(
+                ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+                cwd=root,
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+
+            if branch_result.returncode != 0:
+                return None
+
+            current_branch = branch_result.stdout.strip()
+
+            # Count commits ahead/behind main
+            try:
+                ahead_result = subprocess.run(
+                    ["git", "rev-list", "--count", f"main..{current_branch}"],
+                    cwd=root,
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                )
+                ahead = int(ahead_result.stdout.strip()) if ahead_result.returncode == 0 else 0
+            except Exception:
+                ahead = 0
+
+            try:
+                behind_result = subprocess.run(
+                    ["git", "rev-list", "--count", f"{current_branch}..main"],
+                    cwd=root,
+                    capture_output=True,
+                    text=True,
+                    timeout=5,
+                )
+                behind = int(behind_result.stdout.strip()) if behind_result.returncode == 0 else 0
+            except Exception:
+                behind = 0
+
+            # Count uncommitted changes
+            status_result = subprocess.run(
+                ["git", "status", "--porcelain"],
+                cwd=root,
+                capture_output=True,
+                text=True,
+                timeout=5,
+            )
+
+            uncommitted = len(status_result.stdout.strip().split("\n")) if status_result.returncode == 0 else 0
+
+            return (current_branch, ahead, behind, uncommitted)
+
+        except Exception:
+            return None
+
+    def _analyze_commit_messages(self, root: Path) -> Tuple[float, float, int] | None:
+        """Analyze commit message quality.
+
+        Returns (conventional_commits_pct, avg_message_length, total_commits).
+        """
+        try:
+            # Get recent commits
+            log_result = subprocess.run(
+                ["git", "log", "--max-count=100", "--format=%s"],
+                cwd=root,
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+
+            if log_result.returncode != 0:
+                return None
+
+            messages = log_result.stdout.strip().split("\n")
+            if not messages:
+                return None
+
+            # Check for conventional commits format: type(scope): message or type: message
+            conventional_pattern = re.compile(r"^(feat|fix|docs|style|refactor|perf|test|chore)(\(.+\))?:")
+            conventional_count = sum(1 for msg in messages if conventional_pattern.match(msg))
+
+            total = len(messages)
+            conventional_pct = (conventional_count / total * 100) if total > 0 else 0
+            avg_length = sum(len(msg) for msg in messages) / total if total > 0 else 0
+
+            return (conventional_pct, avg_length, total)
+
+        except Exception:
+            return None
+
+    def _analyze_codeowners(self, root: Path) -> Tuple[bool, float, int] | None:
+        """Analyze CODEOWNERS file coverage.
+
+        Returns (codeowners_exists, coverage_percentage, number_of_rules).
+        """
+        try:
+            # Check for CODEOWNERS file
+            codeowners_paths = [
+                root / "CODEOWNERS",
+                root / ".github" / "CODEOWNERS",
+                root / "docs" / "CODEOWNERS",
+            ]
+
+            codeowners_file = None
+            for path in codeowners_paths:
+                if path.exists():
+                    codeowners_file = path
+                    break
+
+            if not codeowners_file:
+                return (False, 0.0, 0)
+
+            # Parse CODEOWNERS file
+            rules: List[Tuple[str, List[str]]] = []
+            with open(codeowners_file) as f:
+                for line in f:
+                    line = line.strip()
+                    if not line or line.startswith("#"):
+                        continue
+
+                    parts = line.split()
+                    if len(parts) >= 2:
+                        pattern = parts[0]
+                        owners = parts[1:]
+                        rules.append((pattern, owners))
+
+            if not rules:
+                return (True, 0.0, 0)
+
+            # Estimate coverage by checking patterns
+            # (simplified - just count rules)
+            coverage_pct = min(100.0, len(rules) * 10.0)  # Heuristic
+
+            return (True, coverage_pct, len(rules))
+
+        except Exception:
+            return None

pybundle/steps/handoff_md.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import time
+from dataclasses import asdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .base import Step, StepResult
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _safe_read(path: Path) -> str:
+    if not path.exists():
+        return f"(missing: {path.as_posix()})"
+    return path.read_text(encoding="utf-8", errors="replace").strip()
+
+
+def _tool_table(tools_obj: Any) -> list[str]:
+    d = (
+        asdict(tools_obj)
+        if hasattr(tools_obj, "__dataclass_fields__")
+        else dict(tools_obj)
+    )
+    lines = ["| Tool | Status |", "|------|--------|"]
+    for k in sorted(d.keys()):
+        v = d[k]
+        if v:
+            lines.append(f"| `{k}` | ✅ `{v}` |")
+        else:
+            lines.append(f"| `{k}` | ❌ `<missing>` |")
+    return lines
+
+
+class HandoffMarkdownStep(Step):
+    name: str = "generate HANDOFF.md"
+
+    def run(self, ctx: Any) -> StepResult:
+        start = time.time()
+
+        created_utc = getattr(ctx, "created_utc", None) or _utc_now()
+        profile = getattr(ctx, "profile_name", "<unknown>")
+        root_path = Path(getattr(ctx, "root"))
+        project = root_path.name
+        root = str(root_path)
+        workdir_path = Path(getattr(ctx, "workdir"))
+        workdir = str(workdir_path)
+
+        # filenames fixed to match your repo
+        uname = _safe_read(workdir_path / "meta" / "21_uname.txt")
+        pyver = _safe_read(workdir_path / "meta" / "20_python_version.txt")
+
+        redact = bool(getattr(ctx, "redact", True))
+        redact_status = "enabled" if redact else "disabled"
+
+        results: list[Any] = list(getattr(ctx, "results", []))
+        pass_n = sum(1 for r in results if getattr(r, "status", "") == "PASS")
+        fail_n = sum(1 for r in results if getattr(r, "status", "") == "FAIL")
+        skip_n = sum(1 for r in results if getattr(r, "status", "") == "SKIP")
+        total_n = len(results)
+
+        overall = "FAIL" if fail_n else ("DEGRADED" if skip_n else "PASS")
+
+        # tool table
+        tools_obj = getattr(ctx, "tools", None) or getattr(ctx, "tooling", None)
+        tools_table = (
+            _tool_table(tools_obj) if tools_obj is not None else ["(no tools detected)"]
+        )
+
+        command_used = getattr(ctx, "command_used", "") or "(not captured)"
+
+        lines: list[str] = []
+        lines.append("# Bundle Handoff")
+        lines.append("")
+        lines.append("## Overview")
+        lines.append(
+            f"- **Bundle tool:** pybundle {getattr(ctx, 'version', '<unknown>')}"
+        )
+        lines.append(f"- **Profile:** {profile}")
+        lines.append(f"- **Created (UTC):** {created_utc}")
+        lines.append(f"- **Project:** {project}")
+        lines.append(f"- **Root:** {root}")
+        lines.append(f"- **Workdir:** {workdir}")
+        lines.append("")
+        lines.append("## System")
+        lines.append(f"- **OS:** {uname}")
+        lines.append(f"- **Python:** {pyver}")
+        lines.append(f"- **Redaction:** {redact_status}")
+        lines.append("")
+        lines.append("## At a glance")
+
+        lines.append("## AI context summary")
+
+        copy_manifest = _safe_read(
+            workdir_path / "meta" / "50_copy_manifest.txt"
+        ).strip()
+        if copy_manifest:
+            lines.append("### Curated copy")
+            lines.append("```")
+            lines.append(copy_manifest)
+            lines.append("```")
+        else:
+            lines.append("- Curated copy manifest not found.")
+
+        roadmap_json = _safe_read(workdir_path / "meta" / "70_roadmap.json").strip()
+        if roadmap_json:
+            try:
+                import json
+
+                rj = json.loads(roadmap_json)
+                langs = set()
+                for n in rj.get("nodes", []):
+                    if isinstance(n, dict):
+                        lang = n.get("lang")
+                        if lang:
+                            langs.add(lang)
+                eps = rj.get("entrypoints", []) or []
+                lines.append(
+                    f"- **Languages detected:** {', '.join(sorted(langs)) if langs else '(none)'}"
+                )
+                if eps:
+                    lines.append("- **Entrypoints:**")
+                    for ep in eps[:10]:
+                        node = ep.get("node") if isinstance(ep, dict) else None
+                        reason = ep.get("reason") if isinstance(ep, dict) else None
+                        conf = ep.get("confidence") if isinstance(ep, dict) else None
+                        if node:
+                            extra = ""
+                            if reason is not None and conf is not None:
+                                extra = f" — {reason} ({conf}/3)"
+                            lines.append(f"  - `{node}`{extra}")
+                else:
+                    lines.append("- **Entrypoints:** (none detected)")
+            except json.JSONDecodeError as e:
+                # Show EXACTLY why parsing failed - critical for debugging
+                lines.append("- ⚠ Roadmap JSON present but could not be parsed:")
+                lines.append(f"  - Error: {str(e)}")
+                lines.append(f"  - Location: Line {e.lineno}, Column {e.colno}")
+                lines.append(f"  - Raw file included in bundle: `meta/70_roadmap.json`")
+                lines.append(f"  - Try: `python -m json.tool meta/70_roadmap.json` to validate")
+            except Exception as e:
+                lines.append("- ⚠ Roadmap JSON present but could not be parsed:")
+                lines.append(f"  - Error: {type(e).__name__}: {str(e)}")
+                lines.append(f"  - Raw file included in bundle: `meta/70_roadmap.json`")
+        else:
+            lines.append("- Roadmap not found.")
+
+        lines.append("")
+
+        lines.append(f"- **Overall status:** {overall}")
+        lines.append(
+            f"- **Steps:** {total_n} total — {pass_n} PASS, {fail_n} FAIL, {skip_n} SKIP"
+        )
+        lines.append("")
+        lines.append("## Tools")
+        lines.extend(tools_table)
+        lines.append("")
+        lines.append("## Command used")
+        lines.append("```bash")
+        lines.append(command_used)
+        lines.append("```")
+        lines.append("")
+        lines.append("## Reproduction")
+        lines.append("See **REPRO.md** for step-by-step reproduction instructions.")
+        lines.append("")
+
+        out_path = workdir_path / "HANDOFF.md"
+        out_path.write_text("\n".join(lines), encoding="utf-8")
+
+        secs = int(time.time() - start)
+        return StepResult(
+            name=self.name, status="PASS", seconds=secs, note="wrote HANDOFF.md"
+        )

pybundle/steps/import_time.py

@@ -0,0 +1,175 @@
+"""
+Import time analysis - Milestone 3 (v1.4.0)
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .base import StepResult
+from ..context import BundleContext
+
+
+@dataclass
+class ImportTimeStep:
+    """
+    Analyze Python import times using -X importtime to identify slow imports.
+
+    Outputs:
+    - logs/61_import_time.txt: Ranked list of slowest imports
+    """
+
+    name: str = "import_time"
+
+    def run(self, ctx: BundleContext) -> StepResult:
+        start = time.time()
+
+        if ctx.options.no_profile:
+            return StepResult(self.name, "SKIP", 0, "profiling disabled")
+
+        # Find entry point
+        entry_point = self._find_entry_point(ctx)
+
+        if not entry_point:
+            return StepResult(self.name, "SKIP", 0, "no suitable entry point found")
+
+        ctx.emit(f"  Analyzing import time for {entry_point.name}")
+
+        try:
+            # Run with -X importtime
+            result = subprocess.run(
+                [
+                    str(ctx.tools.python),
+                    "-X",
+                    "importtime",
+                    "-c",
+                    f"import runpy; runpy.run_path('{entry_point}')",
+                ],
+                cwd=ctx.root,
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+
+            # Parse and rank import times
+            self._generate_report(
+                result.stderr, ctx.workdir
+            )  # importtime outputs to stderr
+
+            elapsed = int((time.time() - start) * 1000)
+            return StepResult(self.name, "OK", elapsed)
+
+        except subprocess.TimeoutExpired:
+            elapsed = int((time.time() - start) * 1000)
+            return StepResult(self.name, "FAIL", elapsed, "timeout")
+        except Exception as e:
+            elapsed = int((time.time() - start) * 1000)
+            return StepResult(self.name, "FAIL", elapsed, str(e))
+
+    def _find_entry_point(self, ctx: BundleContext) -> Path | None:
+        """Find the best entry point to analyze"""
+        if ctx.options.profile_entry_point:
+            ep = Path(ctx.options.profile_entry_point)
+            if not ep.is_absolute():
+                ep = ctx.root / ctx.options.profile_entry_point
+            if ep.exists() and ep.is_file():
+                return ep
+
+        # Try package/__main__.py
+        pyproject = ctx.root / "pyproject.toml"
+        if pyproject.exists():
+            try:
+                import tomllib
+
+                with pyproject.open("rb") as f:
+                    data = tomllib.load(f)
+                    pkg_name = data.get("project", {}).get("name", "").replace("-", "_")
+                    if pkg_name:
+                        pkg_main = ctx.root / pkg_name / "__main__.py"
+                        if pkg_main.exists():
+                            return pkg_main
+            except Exception:
+                pass
+
+        # Try common entry points
+        for entry in ["__main__.py", "main.py", "app.py", "cli.py"]:
+            path = ctx.root / entry
+            if path.exists():
+                return path
+
+        return None
+
+    def _generate_report(self, importtime_output: str, workdir: Path) -> None:
+        """Parse -X importtime output and generate ranked report"""
+        output_file = workdir / "logs" / "61_import_time.txt"
+        output_file.parent.mkdir(parents=True, exist_ok=True)
+
+        # Parse import times
+        # Format: "import time: self [us] | cumulative | imported package"
+        imports = []
+        for line in importtime_output.splitlines():
+            if "import time:" in line:
+                parts = line.split("|")
+                if len(parts) >= 3:
+                    try:
+                        # Extract times
+                        time_part = parts[0].split(":")[-1].strip()
+                        self_time = int(time_part.split()[0])
+                        cumulative = int(parts[1].strip())
+                        module = parts[2].strip()
+                        imports.append((cumulative, self_time, module))
+                    except (ValueError, IndexError):
+                        continue
+
+        # Sort by cumulative time (descending)
+        imports.sort(reverse=True)
+
+        with output_file.open("w") as f:
+            f.write("=" * 70 + "\n")
+            f.write("IMPORT TIME ANALYSIS\n")
+            f.write("=" * 70 + "\n\n")
+
+            if not imports:
+                f.write("No import time data collected.\n")
+                f.write("\nRaw output:\n")
+                f.write(importtime_output)
+                return
+
+            # Calculate total
+            total_time = sum(imp[0] for imp in imports[:1])  # Top-level cumulative
+
+            f.write(f"Total import time: {total_time / 1000:.1f} ms\n")
+            f.write(f"Number of imports analyzed: {len(imports)}\n\n")
+
+            f.write("TOP 30 SLOWEST IMPORTS (by cumulative time):\n")
+            f.write("-" * 70 + "\n")
+            f.write(f"{'Cumulative (ms)':<18} {'Self (ms)':<15} {'Module'}\n")
+            f.write("-" * 70 + "\n")
+
+            for cumulative, self_time, module in imports[:30]:
+                f.write(
+                    f"{cumulative / 1000:>15.1f}  {self_time / 1000:>12.1f}  {module}\n"
+                )
+
+            # Also show slowest by self time
+            imports_by_self = sorted(imports, key=lambda x: x[1], reverse=True)
+
+            f.write("\n" + "=" * 70 + "\n")
+            f.write("TOP 20 SLOWEST IMPORTS (by self time, excluding children):\n")
+            f.write("-" * 70 + "\n")
+            f.write(f"{'Self (ms)':<15} {'Cumulative (ms)':<18} {'Module'}\n")
+            f.write("-" * 70 + "\n")
+
+            for cumulative, self_time, module in imports_by_self[:20]:
+                f.write(
+                    f"{self_time / 1000:>12.1f}  {cumulative / 1000:>15.1f}  {module}\n"
+                )
+
+            f.write("\n" + "=" * 70 + "\n")
+            f.write("Recommendations:\n")
+            f.write("- Consider lazy imports for modules with high cumulative times\n")
+            f.write("- Review modules with high self times for optimization\n")
+            f.write("- Use conditional imports to defer loading when possible\n")