gwc-pybundle 1.4.5__py3-none-any.whl

pybundle/steps/handoff_md.py

@@ -0,0 +1,167 @@
+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 = "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 Exception:
+                lines.append("- Roadmap JSON present but could not be parsed.")
+        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,165 @@
+"""
+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")

pybundle/steps/interrogate.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import subprocess  # nosec B404 - Required for tool execution, paths validated
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+from .base import StepResult
+from ..context import BundleContext
+from ..tools import which
+
+
+def _repo_has_py_files(root: Path) -> bool:
+    """Fast check if there are Python files to scan."""
+    for p in root.rglob("*.py"):
+        parts = set(p.parts)
+        if (
+            ".venv" not in parts
+            and "__pycache__" not in parts
+            and "node_modules" not in parts
+            and "dist" not in parts
+            and "build" not in parts
+            and "artifacts" not in parts
+        ):
+            return True
+    return False
+
+
+@dataclass
+class InterrogateStep:
+    name: str = "interrogate"
+    target: str = "."
+    outfile: str = "logs/52_docstring_coverage.txt"
+
+    def run(self, ctx: BundleContext) -> StepResult:
+        start = time.time()
+        out = ctx.workdir / self.outfile
+        out.parent.mkdir(parents=True, exist_ok=True)
+
+        interrogate = which("interrogate")
+        if not interrogate:
+            out.write_text(
+                "interrogate not found; skipping (pip install interrogate)\n", 
+                encoding="utf-8"
+            )
+            return StepResult(self.name, "SKIP", 0, "missing interrogate")
+
+        if not _repo_has_py_files(ctx.root):
+            out.write_text(
+                "no .py files detected; skipping interrogate\n", 
+                encoding="utf-8"
+            )
+            return StepResult(self.name, "SKIP", 0, "no python files")
+
+        target_path = ctx.root / self.target
+        cmd = [
+            interrogate,
+            str(target_path),
+            "-v",  # Verbose output
+            "--fail-under", "0",  # Don't fail the step based on coverage percentage
+            "--color",
+        ]
+
+        try:
+            result = subprocess.run(  # nosec B603 - Using full path from which()
+                cmd,
+                cwd=ctx.root,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                timeout=120,
+            )
+            out.write_text(result.stdout, encoding="utf-8")
+            elapsed = int((time.time() - start) * 1000)
+            
+            # interrogate returns 0 even with missing docstrings when --fail-under=0
+            # We consider any execution a success
+            return StepResult(self.name, "OK", elapsed, None)
+        except subprocess.TimeoutExpired:
+            out.write_text("interrogate timed out after 120s\n", encoding="utf-8")
+            return StepResult(self.name, "FAIL", 120000, "timeout")
+        except Exception as e:
+            out.write_text(f"interrogate error: {e}\n", encoding="utf-8")
+            return StepResult(self.name, "FAIL", 0, str(e))

pybundle/steps/license_scan.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import subprocess  # nosec B404 - Required for tool execution, paths validated
+import time
+from dataclasses import dataclass
+
+from .base import StepResult
+from ..context import BundleContext
+from ..tools import which
+
+
+@dataclass
+class LicenseScanStep:
+    name: str = "license scan"
+    outfile: str = "meta/32_licenses.txt"
+
+    def run(self, ctx: BundleContext) -> StepResult:
+        start = time.time()
+        out = ctx.workdir / self.outfile
+        out.parent.mkdir(parents=True, exist_ok=True)
+
+        pip_licenses = which("pip-licenses")
+        if not pip_licenses:
+            out.write_text(
+                "pip-licenses not found; skipping (pip install pip-licenses)\n",
+                encoding="utf-8"
+            )
+            return StepResult(self.name, "SKIP", 0, "missing pip-licenses")
+
+        # Run pip-licenses with detailed output
+        cmd = [
+            pip_licenses,
+            "--format=markdown",  # Markdown table format
+            "--with-urls",  # Include project URLs
+            "--with-description",  # Include package descriptions
+        ]
+
+        try:
+            result = subprocess.run(  # nosec B603 - Using full path from which()
+                cmd,
+                cwd=ctx.root,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                timeout=60,
+            )
+            
+            output = result.stdout
+            
+            # Add license compatibility warnings
+            warnings = self._check_license_compatibility(output)
+            if warnings:
+                output += "\n\n" + "=" * 70 + "\n"
+                output += "LICENSE COMPATIBILITY WARNINGS\n"
+                output += "=" * 70 + "\n\n"
+                output += "\n".join(warnings)
+            
+            out.write_text(output, encoding="utf-8")
+            elapsed = int((time.time() - start) * 1000)
+            
+            return StepResult(self.name, "OK", elapsed, None)
+        except subprocess.TimeoutExpired:
+            out.write_text("pip-licenses timed out after 60s\n", encoding="utf-8")
+            return StepResult(self.name, "FAIL", 60000, "timeout")
+        except Exception as e:
+            out.write_text(f"pip-licenses error: {e}\n", encoding="utf-8")
+            return StepResult(self.name, "FAIL", 0, str(e))
+
+    def _check_license_compatibility(self, output: str) -> list[str]:
+        """Check for common license compatibility issues."""
+        warnings = []
+        
+        # Simple heuristic: look for GPL + permissive license mixing
+        has_gpl = any(gpl in output for gpl in ["GPL", "AGPL", "LGPL"])
+        has_mit = "MIT" in output
+        has_apache = "Apache" in output
+        has_bsd = "BSD" in output
+        
+        if has_gpl and (has_mit or has_apache or has_bsd):
+            warnings.append(
+                "⚠️  Potential GPL compatibility issue detected:\n"
+                "   - GPL/LGPL/AGPL licenses found alongside permissive licenses (MIT/Apache/BSD)\n"
+                "   - Review GPL obligations if redistributing\n"
+                "   - LGPL is generally compatible with permissive licenses\n"
+                "   - Consult legal counsel for production use"
+            )
+        
+        # Check for proprietary or unknown licenses
+        if "UNKNOWN" in output:
+            warnings.append(
+                "⚠️  Packages with UNKNOWN licenses detected:\n"
+                "   - Review manually before distribution\n"
+                "   - May indicate missing license metadata"
+            )
+        
+        return warnings

pybundle/steps/line_profiler.py

@@ -0,0 +1,108 @@
+"""
+Line-by-line profiling with line_profiler - 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 LineProfilerStep:
+    """
+    Line-by-line profiling using line_profiler (optional, requires manual annotation).
+    
+    This step is disabled by default and requires:
+    1. line_profiler installed
+    2. Functions decorated with @profile or listed in config
+    
+    Outputs:
+    - logs/63_line_profile.txt: Line-by-line execution times
+    """
+    
+    name: str = "line_profiler"
+    
+    def run(self, ctx: BundleContext) -> StepResult:
+        start = time.time()
+        
+        # Only run if explicitly enabled
+        if ctx.options.no_profile or not ctx.options.enable_line_profiler:
+            return StepResult(self.name, "SKIP", 0, "line profiler not enabled")
+        
+        # Check if line_profiler is installed
+        if not ctx.tools.line_profiler:
+            return StepResult(self.name, "SKIP", 0, "line_profiler not installed")
+        
+        # Check if entry point exists
+        entry_point = ctx.options.profile_entry_point
+        if not entry_point:
+            return StepResult(self.name, "SKIP", 0, "no entry point specified")
+        
+        target_path = Path(entry_point)
+        if not target_path.is_absolute():
+            target_path = ctx.root / entry_point
+        
+        if not target_path.exists():
+            return StepResult(self.name, "SKIP", 0, f"entry point not found: {entry_point}")
+        
+        ctx.emit(f"  Running line profiler on {target_path.name}")
+        ctx.emit("  Note: Functions must be decorated with @profile")
+        
+        try:
+            # Run line_profiler via kernprof
+            result = subprocess.run(
+                [
+                    str(ctx.tools.line_profiler),
+                    "-l",  # Line-by-line
+                    "-v",  # Verbose output
+                    str(target_path)
+                ],
+                cwd=ctx.root,
+                capture_output=True,
+                text=True,
+                timeout=300  # 5 minute timeout
+            )
+            
+            # Write output
+            output_file = ctx.workdir / "logs" / "63_line_profile.txt"
+            output_file.parent.mkdir(parents=True, exist_ok=True)
+            
+            with output_file.open("w") as f:
+                f.write("=" * 70 + "\n")
+                f.write("LINE-BY-LINE PROFILING (line_profiler)\n")
+                f.write("=" * 70 + "\n\n")
+                
+                if result.returncode == 0:
+                    f.write(result.stdout)
+                    if result.stderr:
+                        f.write("\n\nWarnings/Errors:\n")
+                        f.write(result.stderr)
+                else:
+                    f.write("Line profiling failed or no functions decorated with @profile\n\n")
+                    f.write("To use line_profiler:\n")
+                    f.write("1. Install: pip install line_profiler\n")
+                    f.write("2. Decorate functions with @profile\n")
+                    f.write("3. Specify entry point: --profile-entry-point path/to/script.py\n")
+                    f.write("4. Enable: --enable-line-profiler\n\n")
+                    f.write("STDOUT:\n")
+                    f.write(result.stdout)
+                    f.write("\n\nSTDERR:\n")
+                    f.write(result.stderr)
+            
+            elapsed = int((time.time() - start) * 1000)
+            if result.returncode == 0:
+                return StepResult(self.name, "OK", elapsed)
+            else:
+                return StepResult(self.name, "FAIL", elapsed, f"exit {result.returncode}")
+                
+        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))