gdmcode 0.1.0__py3-none-any.whl

src/tools/document_writer.py

@@ -0,0 +1,171 @@
+"""DocumentWriter — create and modify Word/Excel documents; PDF export via LibreOffice.
+
+All document library imports are guarded so the module loads without optional deps.
+"""
+from __future__ import annotations
+import logging, shutil, subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+log = logging.getLogger(__name__)
+
+__all__ = ["DocumentWriter", "WriteResult", "DocxSpec", "XlsxSpec"]
+
+
+@dataclass
+class WriteResult:
+    path: str
+    format: str
+    bytes_written: int = 0
+    error: Optional[str] = None
+
+    @property
+    def success(self) -> bool:
+        return self.error is None
+
+
+@dataclass
+class DocxSpec:
+    """Declarative spec for a Word document."""
+    title: str = ""
+    author: str = ""
+    sections: list[dict] = field(default_factory=list)
+    # Each section: {"heading": str, "level": int, "paragraphs": [str], "table": [[str]]}
+
+
+@dataclass
+class XlsxSpec:
+    """Declarative spec for an Excel workbook."""
+    sheets: list[dict] = field(default_factory=list)
+    # Each sheet: {"name": str, "headers": [str], "rows": [[str|int|float]]}
+
+
+class DocumentWriter:
+
+    # ── Word ──────────────────────────────────────────────────────────────
+
+    def create_docx(self, spec: DocxSpec, output_path: Path | str) -> WriteResult:
+        output_path = Path(output_path)
+        try:
+            import docx
+        except ImportError:
+            return WriteResult(str(output_path), "docx",
+                               error="python-docx required. pip install 'gdm-code[docs]'")
+        try:
+            doc = docx.Document()
+            props = doc.core_properties
+            if spec.title:
+                props.title = spec.title
+            if spec.author:
+                props.author = spec.author
+            for section in spec.sections:
+                heading = section.get("heading", "")
+                level = section.get("level", 1)
+                if heading:
+                    doc.add_heading(heading, level=level)
+                for para in section.get("paragraphs", []):
+                    doc.add_paragraph(para)
+                table_data = section.get("table")
+                if table_data and len(table_data) > 0:
+                    cols = max(len(r) for r in table_data)
+                    t = doc.add_table(rows=len(table_data), cols=cols, style="Table Grid")
+                    for r_idx, row in enumerate(table_data):
+                        for c_idx, cell in enumerate(row):
+                            t.cell(r_idx, c_idx).text = str(cell)
+            doc.save(str(output_path))
+            return WriteResult(str(output_path), "docx",
+                               bytes_written=output_path.stat().st_size)
+        except Exception as exc:
+            return WriteResult(str(output_path), "docx", error=str(exc))
+
+    def append_docx(self, path: Path | str, paragraphs: list[str],
+                    heading: str = "") -> WriteResult:
+        path = Path(path)
+        try:
+            import docx
+        except ImportError:
+            return WriteResult(str(path), "docx",
+                               error="python-docx required. pip install 'gdm-code[docs]'")
+        try:
+            doc = docx.Document(str(path))
+            if heading:
+                doc.add_heading(heading, level=2)
+            for para in paragraphs:
+                doc.add_paragraph(para)
+            doc.save(str(path))
+            return WriteResult(str(path), "docx", bytes_written=path.stat().st_size)
+        except Exception as exc:
+            return WriteResult(str(path), "docx", error=str(exc))
+
+    # ── Excel ─────────────────────────────────────────────────────────────
+
+    def create_xlsx(self, spec: XlsxSpec, output_path: Path | str) -> WriteResult:
+        output_path = Path(output_path)
+        try:
+            import openpyxl
+            from openpyxl.styles import Font
+        except ImportError:
+            return WriteResult(str(output_path), "xlsx",
+                               error="openpyxl required. pip install 'gdm-code[docs]'")
+        try:
+            wb = openpyxl.Workbook()
+            wb.remove(wb.active)
+            for sheet_spec in spec.sheets:
+                ws = wb.create_sheet(title=sheet_spec.get("name", "Sheet"))
+                headers = sheet_spec.get("headers", [])
+                if headers:
+                    ws.append(headers)
+                    for cell in ws[1]:
+                        cell.font = Font(bold=True)
+                for row in sheet_spec.get("rows", []):
+                    ws.append(list(row))
+            wb.save(str(output_path))
+            return WriteResult(str(output_path), "xlsx",
+                               bytes_written=output_path.stat().st_size)
+        except Exception as exc:
+            return WriteResult(str(output_path), "xlsx", error=str(exc))
+
+    def update_xlsx_cell(self, path: Path | str, sheet_name: str,
+                         row: int, col: int, value) -> WriteResult:
+        """Update a single cell (1-indexed row/col) in an existing xlsx."""
+        path = Path(path)
+        try:
+            import openpyxl
+        except ImportError:
+            return WriteResult(str(path), "xlsx",
+                               error="openpyxl required. pip install 'gdm-code[docs]'")
+        try:
+            wb = openpyxl.load_workbook(str(path))
+            if sheet_name not in wb.sheetnames:
+                return WriteResult(str(path), "xlsx",
+                                   error=f"Sheet '{sheet_name}' not found")
+            ws = wb[sheet_name]
+            ws.cell(row=row, column=col, value=value)
+            wb.save(str(path))
+            return WriteResult(str(path), "xlsx", bytes_written=path.stat().st_size)
+        except Exception as exc:
+            return WriteResult(str(path), "xlsx", error=str(exc))
+
+    # ── PDF conversion ────────────────────────────────────────────────────
+
+    def docx_to_pdf(self, docx_path: Path | str, output_dir: Path | str = None) -> WriteResult:
+        docx_path = Path(docx_path)
+        output_dir = Path(output_dir) if output_dir else docx_path.parent
+        if not shutil.which("libreoffice"):
+            return WriteResult(str(docx_path), "pdf",
+                               error="LibreOffice not found. Install LibreOffice to enable PDF export.")
+        try:
+            result = subprocess.run(
+                ["libreoffice", "--headless", "--convert-to", "pdf",
+                 "--outdir", str(output_dir), str(docx_path)],
+                capture_output=True, timeout=60,
+            )
+            if result.returncode != 0:
+                return WriteResult(str(docx_path), "pdf",
+                                   error=result.stderr.decode(errors="replace"))
+            pdf_path = output_dir / (docx_path.stem + ".pdf")
+            return WriteResult(str(pdf_path), "pdf",
+                               bytes_written=pdf_path.stat().st_size if pdf_path.exists() else 0)
+        except Exception as exc:
+            return WriteResult(str(docx_path), "pdf", error=str(exc))

src/tools/impact_tools.py

@@ -0,0 +1,240 @@
+"""Impact analysis tool — blast radius before signature changes.
+
+Given a symbol name (function, class, or variable), returns:
+- Every file that calls or imports it
+- Line numbers and context snippets for each call site
+- Suggested test files to run after the change
+- Risk level: low / medium / high based on total caller count
+
+Call before any breaking rename or signature change to understand scope.
+"""
+from __future__ import annotations
+
+import logging
+import re
+import uuid
+from pathlib import Path
+from typing import Any, ClassVar
+
+from src.tools import REGISTRY, ToolBase, ToolResult
+
+__all__ = ["ImpactAnalysisTool"]
+
+log = logging.getLogger(__name__)
+
+_EXCLUDED_DIRS: frozenset[str] = frozenset(
+    {".git", "__pycache__", "node_modules", ".venv", "venv", "dist", "build"}
+)
+_SOURCE_EXTS: frozenset[str] = frozenset(
+    {".py", ".ts", ".js", ".tsx", ".jsx"}
+)
+_MAX_HITS_PER_FILE: int = 5
+_RISK_LOW: int = 2
+_RISK_MEDIUM: int = 10
+
+
+# ---------------------------------------------------------------------------
+# Tool
+# ---------------------------------------------------------------------------
+
+class ImpactAnalysisTool(ToolBase):
+    """Analyse the blast radius of a rename or signature change.
+
+    Returns all call sites for a symbol with file/line info, a risk level
+    (low / medium / high), and suggested test targets.
+
+    **Call before any breaking refactor.**
+    """
+
+    name: ClassVar[str] = "impact_analysis"
+    description: ClassVar[str] = (
+        "Analyse the blast radius of a rename or signature change. "
+        "Returns all callers of a symbol with file/line info, risk level, "
+        "and suggested tests to run. Call before any breaking refactor."
+    )
+    input_schema: ClassVar[dict[str, Any]] = {
+        "type": "object",
+        "required": ["symbol"],
+        "properties": {
+            "symbol": {
+                "type": "string",
+                "description": "The function, class, or variable name to analyse.",
+            },
+            "project_root": {
+                "type": "string",
+                "description": "Root directory. Defaults to cwd.",
+            },
+            "include_tests": {
+                "type": "boolean",
+                "description": "Include test files in analysis (default: false).",
+            },
+            "change_type": {
+                "type": "string",
+                "enum": ["rename", "signature_change", "delete", "behavior_change"],
+                "description": "Type of change being made",
+                "default": "signature_change",
+            },
+            "new_signature": {
+                "type": "string",
+                "description": "New signature (for rename/signature_change)",
+                "default": "",
+            },
+        },
+    }
+
+    def execute(self, args: dict[str, Any]) -> ToolResult:
+        symbol: str = (args.get("symbol") or "").strip()
+        if not symbol:
+            return ToolResult(output="", error="'symbol' is required")
+
+        root = Path(args.get("project_root") or Path.cwd()).resolve()
+        include_tests: bool = args.get("include_tests", False)
+        change_type: str = args.get("change_type", "signature_change")
+
+        try:
+            callers = self._find_callers(symbol, root, include_tests)
+            is_public = self._is_public_api(symbol, root)
+            semver = self._semver_recommendation(symbol, callers, is_public)
+
+            from src.models.schemas import ImpactReport
+            impact_report = ImpactReport(
+                symbol=symbol,
+                callers_count=len(callers),
+                callers=callers,
+                affected_tests=[c["file"] for c in callers if "test" in c["file"].lower()],
+                is_public_api=is_public,
+                semver_recommendation=semver,
+                change_type=change_type,
+            )
+
+            tool_result = ToolResult(output=self._format_report(symbol, callers))
+            tool_result.metadata["structured"] = impact_report.model_dump()
+            return tool_result
+        except Exception as exc:  # noqa: BLE001
+            log.warning("impact_analysis failed for %r: %s", symbol, exc)
+            return ToolResult(output="", error=str(exc))
+
+    # ------------------------------------------------------------------
+    # Caller discovery
+    # ------------------------------------------------------------------
+
+    def _find_callers(
+        self, symbol: str, root: Path, include_tests: bool
+    ) -> list[dict[str, Any]]:
+        """Try CodeIndex first (fast), fall back to regex grep."""
+        try:
+            from src.memory.code_index import CodeIndex
+            from src.memory.db import GdmDatabase
+
+            db = GdmDatabase(project_root=root)
+            project_id = str(uuid.uuid5(uuid.NAMESPACE_URL, str(root)))
+            idx = CodeIndex(db=db, project_id=project_id, project_root=root)
+            raw = idx.find_callers(symbol)
+            if raw:
+                callers = [{"file": file, "line": line, "context": ""} for file, line in raw]
+                if not include_tests:
+                    callers = [
+                        c for c in callers
+                        if "test" not in c["file"].lower()
+                    ]
+                return callers
+        except (ImportError, OSError):
+            pass  # fall through to grep
+
+        raw_tuples = self._grep_callers(symbol, root)
+        callers = [{"file": f, "line": ln, "context": ctx} for f, ln, ctx in raw_tuples]
+        if not include_tests:
+            callers = [c for c in callers if "test" not in c["file"].lower()]
+        return callers
+
+    def _grep_callers(self, symbol: str, root: Path) -> list[tuple[str, int, str]]:
+        """Regex-based fallback: scan Python files for symbol references, excluding definition lines."""
+        results: list[tuple[str, int, str]] = []
+        for py_file in root.rglob("*.py"):
+            if any(part in _EXCLUDED_DIRS for part in py_file.parts):
+                continue
+            try:
+                content = py_file.read_text(errors="ignore")
+            except OSError:
+                continue
+            for i, line in enumerate(content.splitlines(), 1):
+                if re.match(rf'^\s*(?:def|class)\s+{re.escape(symbol)}\b', line):
+                    continue
+                if re.search(rf'\b{re.escape(symbol)}\s*[\(\[]', line):
+                    results.append((str(py_file), i, line.strip()))
+        return results
+
+    # ------------------------------------------------------------------
+    # New helper methods
+    # ------------------------------------------------------------------
+
+    def _semver_recommendation(self, symbol: str, callers: list, is_public: bool) -> str:
+        if not callers:
+            return "PATCH — no callers, internal cleanup"
+        if is_public:
+            return "MAJOR — exported symbol changed, breaking consumers"
+        if len(callers) > 10:
+            return "MINOR — internal change affecting many files"
+        return "PATCH — local change, limited blast radius"
+
+    def _is_public_api(self, symbol: str, project_root: Path) -> bool:
+        for init in project_root.rglob("__init__.py"):
+            try:
+                if symbol in init.read_text(errors="ignore"):
+                    return True
+            except OSError:
+                continue
+        return False
+
+    # ------------------------------------------------------------------
+    # Report formatting
+    # ------------------------------------------------------------------
+
+    def _format_report(
+        self, symbol: str, callers: list[dict[str, Any]]
+    ) -> str:
+        if not callers:
+            return (
+                f"Symbol `{symbol}` not found in any source file.\n"
+                "✅  Safe to rename — no call sites detected."
+            )
+
+        by_file: dict[str, list[dict[str, Any]]] = {}
+        test_files: set[str] = set()
+        for c in callers:
+            by_file.setdefault(c["file"], []).append(c)
+            if "test" in c["file"].lower():
+                test_files.add(c["file"])
+
+        total = len(callers)
+        file_count = len(by_file)
+        risk = "low" if total <= _RISK_LOW else "medium" if total <= _RISK_MEDIUM else "high"
+        icons = {"low": "🟢", "medium": "🟡", "high": "🔴"}
+
+        lines: list[str] = [
+            f"## Impact analysis for `{symbol}`",
+            "",
+            f"Risk: {icons[risk]} **{risk.upper()}** — {total} reference(s) in {file_count} file(s)",
+            "",
+            "### Call sites",
+        ]
+
+        for filepath, hits in sorted(by_file.items()):
+            lines.append(f"\n**{filepath}**")
+            for h in hits[:_MAX_HITS_PER_FILE]:
+                lines.append(f"  L{h['line']}: `{h['context']}`")
+            if len(hits) > _MAX_HITS_PER_FILE:
+                lines.append(f"  … and {len(hits) - _MAX_HITS_PER_FILE} more")
+
+        lines += ["", "### Suggested tests after change"]
+        if test_files:
+            for tf in sorted(test_files):
+                lines.append(f"  pytest {tf}")
+        else:
+            lines.append(f"  pytest -k {symbol!r}")
+
+        return "\n".join(lines)
+
+
+# Self-register
+REGISTRY.register(ImpactAnalysisTool())

src/tools/playwright_tool.py

@@ -0,0 +1,172 @@
+"""Playwright-based browser automation tool for gdm agents.
+
+Provides a high-level async interface for navigating pages, taking screenshots,
+clicking elements, filling forms, and evaluating JavaScript.
+
+playwright is an optional dependency — a clear ImportError with install
+instructions is raised if the package is missing.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+try:
+    from playwright.async_api import async_playwright
+    _PLAYWRIGHT_AVAILABLE = True
+except ImportError:
+    _PLAYWRIGHT_AVAILABLE = False
+    async_playwright = None  # type: ignore[assignment]
+
+__all__ = ["PlaywrightResult", "PlaywrightTool"]
+
+# ---------------------------------------------------------------------------
+# JS safety: patterns blocked in evaluate()
+# ---------------------------------------------------------------------------
+
+_DANGEROUS_JS_PATTERNS: tuple[str, ...] = (
+    "fetch(",
+    "XMLHttpRequest",
+    "eval(",
+    "import(",
+)
+
+
+# ---------------------------------------------------------------------------
+# PlaywrightResult
+# ---------------------------------------------------------------------------
+
+@dataclass
+class PlaywrightResult:
+    """Result of a Playwright browser operation."""
+
+    success: bool
+    data: Any = None
+    error: str | None = None
+    screenshot: bytes | None = None
+
+
+# ---------------------------------------------------------------------------
+# PlaywrightTool
+# ---------------------------------------------------------------------------
+
+class PlaywrightTool:
+    """Async browser automation tool backed by Playwright.
+
+    Usage (async context manager)::
+
+        async with PlaywrightTool() as tool:
+            await tool.navigate("https://example.com")
+            result = await tool.screenshot()
+
+    Requires playwright to be installed::
+
+        pip install playwright && playwright install chromium
+    """
+
+    def __init__(self) -> None:
+        self._playwright: Any = None
+        self._browser: Any = None
+        self._page: Any = None
+
+    # -- Lifecycle -----------------------------------------------------------
+
+    @staticmethod
+    def _check_playwright() -> None:
+        """Raise ImportError with install hint if playwright is not available."""
+        if not _PLAYWRIGHT_AVAILABLE:
+            raise ImportError(
+                "Install playwright: pip install playwright && playwright install chromium"
+            )
+
+    async def __aenter__(self) -> "PlaywrightTool":
+        self._check_playwright()
+        self._playwright = await async_playwright().start()
+        self._browser = await self._playwright.chromium.launch(headless=True)
+        self._page = await self._browser.new_page()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.close()
+
+    # -- Public async API ----------------------------------------------------
+
+    async def navigate(self, url: str) -> PlaywrightResult:
+        """Navigate to *url* and return the page title."""
+        self._check_playwright()
+        try:
+            await self._page.goto(url)
+            title = await self._page.title()
+            return PlaywrightResult(success=True, data=title)
+        except Exception as exc:  # noqa: BLE001
+            return PlaywrightResult(success=False, error=str(exc))
+
+    async def screenshot(self, full_page: bool = False) -> PlaywrightResult:
+        """Take a screenshot of the current page.
+
+        Returns raw PNG bytes in ``result.screenshot``.
+        """
+        self._check_playwright()
+        try:
+            png_bytes = await self._page.screenshot(full_page=full_page)
+            return PlaywrightResult(success=True, screenshot=png_bytes)
+        except Exception as exc:  # noqa: BLE001
+            return PlaywrightResult(success=False, error=str(exc))
+
+    async def click(self, selector: str) -> PlaywrightResult:
+        """Click the element matching *selector*."""
+        self._check_playwright()
+        try:
+            await self._page.click(selector)
+            return PlaywrightResult(success=True)
+        except Exception as exc:  # noqa: BLE001
+            return PlaywrightResult(success=False, error=str(exc))
+
+    async def fill(self, selector: str, value: str) -> PlaywrightResult:
+        """Fill an input element matching *selector* with *value*."""
+        self._check_playwright()
+        try:
+            await self._page.fill(selector, value)
+            return PlaywrightResult(success=True)
+        except Exception as exc:  # noqa: BLE001
+            return PlaywrightResult(success=False, error=str(exc))
+
+    async def evaluate(self, expression: str) -> PlaywrightResult:
+        """Evaluate a JavaScript *expression* in the page context.
+
+        Blocks dangerous patterns: ``fetch(``, ``XMLHttpRequest``,
+        ``eval(``, ``import(``.
+        """
+        self._check_playwright()
+        for pattern in _DANGEROUS_JS_PATTERNS:
+            if pattern in expression:
+                return PlaywrightResult(
+                    success=False,
+                    error=f"Unsafe JS pattern rejected: '{pattern}'",
+                )
+        try:
+            result = await self._page.evaluate(expression)
+            return PlaywrightResult(success=True, data=result)
+        except Exception as exc:  # noqa: BLE001
+            return PlaywrightResult(success=False, error=str(exc))
+
+    async def get_text(self, selector: str = "body") -> PlaywrightResult:
+        """Return the inner text of *selector* (default: ``body``)."""
+        self._check_playwright()
+        try:
+            text = await self._page.inner_text(selector)
+            return PlaywrightResult(success=True, data=text)
+        except Exception as exc:  # noqa: BLE001
+            return PlaywrightResult(success=False, error=str(exc))
+
+    async def close(self) -> None:
+        """Close the browser and clean up Playwright resources."""
+        try:
+            if self._browser is not None:
+                await self._browser.close()
+                self._browser = None
+            if self._playwright is not None:
+                await self._playwright.stop()
+                self._playwright = None
+        except Exception:  # noqa: BLE001
+            pass